@tenex-chat/backend 0.9.1

package/src/event-handler/newConversation.ts

@@ -0,0 +1,165 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { NDKArticle } from "@nostr-dev-kit/ndk";
+import { trace } from "@opentelemetry/api";
+import chalk from "chalk";
+import type { AgentExecutor } from "../agents/execution/AgentExecutor";
+import { createExecutionContext } from "../agents/execution/ExecutionContextFactory";
+import { ConversationStore } from "../conversations/ConversationStore";
+import type { ConversationMetadata } from "../conversations/types";
+import { AgentEventDecoder } from "../nostr/AgentEventDecoder";
+import { getNDK } from "../nostr/ndkClient";
+import { TagExtractor } from "../nostr/TagExtractor";
+import { getProjectContext } from "@/services/projects";
+import { formatAnyError } from "@/lib/error-formatter";
+import { logger } from "../utils/logger";
+import { AgentRouter } from "@/services/dispatch/AgentRouter";
+
+/**
+ * Fetch a kind 30023 (NDKArticle) from an a-tag reference.
+ * @param aTagValue - The a-tag value in format "30023:pubkey:d-tag"
+ * @returns The article metadata or null if not found
+ */
+async function fetchReferencedArticle(
+    aTagValue: string
+): Promise<ConversationMetadata["referencedArticle"] | null> {
+    try {
+        const parts = aTagValue.split(":");
+        if (parts.length < 3 || parts[0] !== "30023") {
+            return null;
+        }
+
+        const [, pubkey, ...dTagParts] = parts;
+        const dTag = dTagParts.join(":"); // Handle d-tags that contain colons
+
+        const ndk = getNDK();
+        const filter = {
+            kinds: [30023],
+            authors: [pubkey],
+            "#d": [dTag],
+        };
+
+        const events = await ndk.fetchEvents(filter);
+        if (events.size === 0) {
+            logger.debug(chalk.yellow(`Referenced article not found: ${aTagValue}`));
+            return null;
+        }
+
+        const event = Array.from(events)[0];
+        const article = NDKArticle.from(event);
+
+        logger.info(chalk.cyan(`📄 Fetched referenced article: "${article.title || dTag}"`));
+
+        return {
+            title: article.title || dTag,
+            content: article.content || "",
+            dTag,
+        };
+    } catch (error) {
+        logger.debug(chalk.yellow(`Failed to fetch referenced article: ${formatAnyError(error)}`));
+        return null;
+    }
+}
+
+/**
+ * Extract and fetch the first kind 30023 article reference from an event's a-tags.
+ * @param event - The event to extract article references from
+ * @returns The article metadata or null if none found
+ */
+async function extractReferencedArticle(
+    event: NDKEvent
+): Promise<ConversationMetadata["referencedArticle"] | null> {
+    const aTags = TagExtractor.getATags(event);
+
+    // Find the first a-tag referencing a kind 30023 (article)
+    const articleATag = aTags.find((tag) => tag.startsWith("30023:"));
+    if (!articleATag) {
+        return null;
+    }
+
+    return fetchReferencedArticle(articleATag);
+}
+
+interface EventHandlerContext {
+    agentExecutor: AgentExecutor;
+    /**
+     * Project directory (normal git repository root).
+     * Worktrees are in .worktrees/ subdirectory.
+     */
+    projectBasePath: string;
+}
+
+export const handleNewConversation = async (
+    event: NDKEvent,
+    context: EventHandlerContext
+): Promise<void> => {
+    try {
+        // Create conversation
+        const conversation = await ConversationStore.create(event);
+
+        // Check for referenced kind 30023 articles and populate metadata
+        const referencedArticle = await extractReferencedArticle(event);
+        if (referencedArticle) {
+            conversation.updateMetadata({ referencedArticle });
+            await conversation.save();
+
+            const activeSpan = trace.getActiveSpan();
+            if (activeSpan) {
+                activeSpan.addEvent("referenced_article_loaded", {
+                    "article.title": referencedArticle.title,
+                    "article.dTag": referencedArticle.dTag,
+                    "article.content_length": referencedArticle.content.length,
+                });
+            }
+        }
+
+        // Get project context
+        const projectCtx = getProjectContext();
+
+        // Use AgentRouter to resolve target agents (includes project validation for global agents)
+        const targetAgents = AgentRouter.resolveTargetAgents(event, projectCtx);
+
+        // Add telemetry for routing decision
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+            const mentionedPubkeys = AgentEventDecoder.getMentionedPubkeys(event);
+            activeSpan.addEvent("agent_routing", {
+                "routing.mentioned_pubkeys_count": mentionedPubkeys.length,
+                "routing.resolved_agent_count": targetAgents.length,
+                "routing.agent_names": targetAgents.map((a) => a.name).join(", "),
+                "routing.agent_roles": targetAgents.map((a) => a.role).join(", "),
+            });
+        }
+
+        // If no valid agents found (filtered by project context), return
+        if (targetAgents.length === 0) {
+            logger.info(
+                chalk.gray(
+                    "New conversation - no valid agents to route to (may have been filtered by project context)"
+                )
+            );
+            if (activeSpan) {
+                activeSpan.addEvent("agent_routing_failed", { reason: "no_agents_resolved" });
+            }
+            return;
+        }
+
+        // Use first agent for new conversation
+        const targetAgent = targetAgents[0];
+
+        // Create execution context (new conversations don't have branch tags)
+        const executionContext = await createExecutionContext({
+            agent: targetAgent,
+            conversationId: conversation.id,
+            projectBasePath: context.projectBasePath,
+            triggeringEvent: event,
+            mcpManager: projectCtx.mcpManager,
+        });
+
+        // Execute with the appropriate agent
+        await context.agentExecutor.execute(executionContext);
+
+        logger.info(chalk.green("✅ Conversation routed successfully"));
+    } catch (error) {
+        logger.info(chalk.red(`❌ Failed to route conversation: ${formatAnyError(error)}`));
+    }
+};

package/src/event-handler/project.ts

@@ -0,0 +1,166 @@
+import type { NDKEvent, NDKProject } from "@nostr-dev-kit/ndk";
+import { NDKMCPTool } from "../events/NDKMCPTool";
+import { getNDK } from "../nostr";
+import { TagExtractor } from "../nostr/TagExtractor";
+import { getProjectContext } from "@/services/projects";
+import {
+    getInstalledMCPEventIds,
+    installMCPServerFromEvent,
+    removeMCPServerByEventId,
+} from "../services/mcp/mcpInstaller";
+import { installAgentFromNostr } from "../agents/agent-installer";
+import { logger } from "../utils/logger";
+import { trace } from "@opentelemetry/api";
+
+/**
+ * Handles project update events by syncing agent and MCP tool definitions.
+ * When a project event is received, this function:
+ * 1. Checks if the event is for the currently loaded project
+ * 2. Identifies new agents and MCP tools that have been added to the project
+ * 3. Fetches definitions from Nostr for new agents and MCP tools
+ * 4. Saves definitions to disk and registers them
+ * 5. Updates the ProjectContext with the new configuration
+ */
+export async function handleProjectEvent(event: NDKEvent): Promise<void> {
+    const title = TagExtractor.getTagValue(event, "title") || "Untitled";
+
+    // Extract agent event IDs from the project
+    const agentEventIds = TagExtractor.getTagValues(event, "agent")
+        .filter((id): id is string => typeof id === "string");
+
+    // Extract MCP tool event IDs from the project
+    const mcpEventIds = TagExtractor.getTagValues(event, "mcp")
+        .filter((id): id is string => typeof id === "string");
+
+    trace.getActiveSpan()?.addEvent("project.update_received", {
+        "project.title": title,
+        "project.agent_count": agentEventIds.length,
+        "project.mcp_count": mcpEventIds.length,
+    });
+
+    try {
+        const currentContext = getProjectContext();
+        const metadataPath = currentContext.agentRegistry.getMetadataPath();
+
+        // Check if this is the same project that's currently loaded
+        const currentProjectDTag = currentContext.project.dTag;
+        const eventDTag = TagExtractor.getDTag(event);
+
+        if (currentProjectDTag !== eventDTag) {
+            return;
+        }
+
+        const ndkProject = event as NDKProject;
+
+        // Track which agents need to be added or updated
+        const currentAgentEventIds = new Set<string>();
+        for (const agent of currentContext.agents.values()) {
+            if (agent.eventId) {
+                currentAgentEventIds.add(agent.eventId);
+            }
+        }
+
+        // Find new agents that need to be fetched
+        const newAgentEventIds = agentEventIds.filter(
+            (id) => !!id && !currentAgentEventIds.has(id)
+        );
+
+        // Find agents that need to be removed (exist locally but not in the project)
+        const newAgentEventIdsSet = new Set(agentEventIds);
+        const agentsToRemove = Array.from(currentAgentEventIds).filter(
+            (id) => !newAgentEventIdsSet.has(id)
+        );
+
+        // Handle agent removals first
+        if (agentsToRemove.length > 0) {
+            const agentRegistry = currentContext.agentRegistry;
+
+            for (const eventId of agentsToRemove) {
+                // Find agent by eventId
+                const agent = Array.from(currentContext.agents.values()).find(
+                    (a) => a.eventId === eventId
+                );
+
+                if (agent) {
+                    try {
+                        await agentRegistry.removeAgentFromProject(agent.slug);
+                    } catch (error) {
+                        logger.error(`Error removing agent ${agent.slug}`, { error });
+                    }
+                }
+            }
+        }
+
+        // Process agent and MCP tool changes
+        const ndk = getNDK();
+
+        // Fetch and install new agent definitions using shared function
+        if (newAgentEventIds.length > 0) {
+            for (const eventId of newAgentEventIds) {
+                try {
+                    await installAgentFromNostr(eventId, undefined, ndk);
+                } catch (error) {
+                    logger.error("Failed to install agent from event", { eventId, error });
+                }
+            }
+            // Reload the agent registry to pick up new agents
+            await currentContext.agentRegistry.loadFromProject(ndkProject);
+        }
+
+        // Process MCP tool changes
+
+        // Get currently installed MCP event IDs (only those with event IDs)
+        const installedMCPEventIds = await getInstalledMCPEventIds(metadataPath);
+
+        // Find new MCP tools that need to be fetched
+        const newMCPEventIds = mcpEventIds.filter((id) => !!id && !installedMCPEventIds.has(id));
+
+        // Find MCP tools that need to be removed (exist locally but not in the project)
+        const newMCPEventIdsSet = new Set(mcpEventIds);
+        const mcpToolsToRemove = Array.from(installedMCPEventIds).filter(
+            (id) => !newMCPEventIdsSet.has(id)
+        );
+
+        // Handle MCP tool removals first
+        for (const eventId of mcpToolsToRemove) {
+            try {
+                await removeMCPServerByEventId(metadataPath, eventId);
+            } catch (error) {
+                logger.error("Failed to remove MCP tool", { error, eventId });
+            }
+        }
+
+        // Fetch and install new MCP tools
+        for (const eventId of newMCPEventIds) {
+            try {
+                const mcpEvent = await ndk.fetchEvent(eventId);
+                if (mcpEvent) {
+                    const mcpTool = NDKMCPTool.from(mcpEvent);
+                    await installMCPServerFromEvent(metadataPath, mcpTool);
+                }
+            } catch (error) {
+                logger.error("Failed to fetch or install MCP tool", { error, eventId });
+            }
+        }
+
+        // Reload MCP service if there were any MCP tool changes
+        const hasMCPChanges = newMCPEventIds.length > 0 || mcpToolsToRemove.length > 0;
+        if (hasMCPChanges && currentContext.mcpManager) {
+            await currentContext.mcpManager.reload(metadataPath);
+        }
+
+        // Update the existing project context atomically
+        // This will reload agents from the project
+        await currentContext.updateProjectData(ndkProject);
+
+        trace.getActiveSpan()?.addEvent("project.updated", {
+            "project.total_agents": currentContext.agents.size,
+            "project.agents_added": newAgentEventIds.length,
+            "project.agents_removed": agentsToRemove.length,
+            "project.mcp_added": newMCPEventIds.length,
+            "project.mcp_removed": mcpToolsToRemove.length,
+        });
+    } catch (error) {
+        logger.error("Failed to update project from event", { error });
+    }
+}

package/src/event-handler/reply.ts

@@ -0,0 +1,18 @@
+import type { AgentExecutor } from "@/agents/execution/AgentExecutor";
+import { AgentDispatchService } from "@/services/dispatch/AgentDispatchService";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+interface EventHandlerContext {
+    agentExecutor: AgentExecutor;
+}
+
+/**
+ * Main entry point for handling chat messages.
+ */
+export const handleChatMessage = async (
+    event: NDKEvent,
+    context: EventHandlerContext
+): Promise<void> => {
+    const dispatcher = AgentDispatchService.getInstance();
+    await dispatcher.dispatch(event, context);
+};

package/src/events/NDKAgentDefinition.ts

@@ -0,0 +1,292 @@
+import type NDK from "@nostr-dev-kit/ndk";
+import { NDKEvent, type NDKRawEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Tuple type for e-tags: ["e", eventId, relayUrl, marker]
+ */
+export type ETag = [marker: "e", eventId: string, relayUrl: string, tagMarker: string];
+
+/**
+ * Parsed e-tag reference with typed fields
+ */
+export interface ETagReference {
+    eventId: string;
+    relayUrl?: string;
+    marker?: string;
+}
+
+export class NDKAgentDefinition extends NDKEvent {
+    static kind = 4199;
+    static kinds = [4199];
+
+    constructor(ndk?: NDK, event?: NDKEvent | NDKRawEvent) {
+        super(ndk, event);
+        this.kind ??= 4199;
+    }
+
+    static from(event: NDKEvent): NDKAgentDefinition {
+        return new NDKAgentDefinition(event.ndk, event);
+    }
+
+    /**
+     * The canonical title/name of the agent.
+     * Maps to the "title" tag.
+     */
+    get title(): string | undefined {
+        return this.tagValue("title");
+    }
+
+    set title(value: string | undefined) {
+        this.setOptionalTag("title", value);
+    }
+
+    /**
+     * Alias for `title`. Prefer using `title` directly.
+     * @deprecated Use `title` instead. Will be removed in a future version.
+     */
+    get name(): string | undefined {
+        return this.title;
+    }
+
+    /**
+     * @deprecated Use `title` instead. Will be removed in a future version.
+     */
+    set name(value: string | undefined) {
+        this.title = value;
+    }
+
+    get description(): string | undefined {
+        return this.tagValue("description");
+    }
+
+    /**
+     * A one-liner description of the agent's purpose or functionality.
+     */
+    set description(value: string | undefined) {
+        this.setOptionalTag("description", value);
+    }
+
+    /**
+     * Extended markdown description from the event content field.
+     * MAY contain markdown-formatted extended description of the agent.
+     */
+    get markdownDescription(): string | undefined {
+        return this.content || undefined;
+    }
+
+    /**
+     * Set the extended markdown description in the event content field.
+     */
+    set markdownDescription(value: string | undefined) {
+        this.content = value ?? "";
+    }
+
+    get role(): string | undefined {
+        return this.tagValue("role");
+    }
+
+    /**
+     * The expertise and personality for this agent.
+     * This shapes how the agent interacts with users and other agents.
+     */
+    set role(value: string | undefined) {
+        this.setOptionalTag("role", value);
+    }
+
+    get instructions(): string | undefined {
+        return this.tagValue("instructions");
+    }
+
+    /**
+     * Detailed instructions or guidelines for the agent's operation.
+     */
+    set instructions(value: string | undefined) {
+        this.setOptionalTag("instructions", value);
+    }
+
+    get version(): number {
+        const val = this.tagValue("ver");
+        if (val === undefined) return 1; // Default version if not specified
+        const parsed = Number.parseInt(val, 10);
+        return Number.isNaN(parsed) ? 1 : parsed; // Fallback to 1 if parsing fails
+    }
+
+    set version(value: number) {
+        this.removeTag("ver");
+        this.tags.push(["ver", value.toString()]);
+    }
+
+    get useCriteria(): string | undefined {
+        return this.tagValue("use-criteria");
+    }
+
+    /**
+     * Criteria for when this agent should be selected or used.
+     * This helps with agent routing and selection.
+     */
+    set useCriteria(value: string | undefined) {
+        this.setOptionalTag("use-criteria", value);
+    }
+
+    get category(): string | undefined {
+        return this.tagValue("category");
+    }
+
+    /**
+     * Category for the agent (e.g., 'developer', 'analyst', 'assistant').
+     */
+    set category(value: string | undefined) {
+        this.setOptionalTag("category", value);
+    }
+
+    get slug(): string | undefined {
+        return this.tagValue("d");
+    }
+
+    /**
+     * The slug identifier for this agent definition.
+     * This is used to find different versions from the same author of the same agent
+     * (e.g., version 1, 2, 3 of a 'human-replica' agent would all share ["d", "human-replica"]).
+     *
+     * Note: Unlike other setters, this uses `value !== undefined` instead of truthy check
+     * because empty string is a valid d-tag value per Nostr conventions. Only `undefined`
+     * should clear the tag. This is intentionally different from setOptionalTag behavior.
+     */
+    set slug(value: string | undefined) {
+        this.removeTag("d");
+        if (value !== undefined) this.tags.push(["d", value]);
+    }
+
+    /**
+     * Get script e-tags from the agent definition.
+     * Script e-tags reference kind 1063 (NIP-94 file metadata) events
+     * that contain files bundled with the agent.
+     *
+     * @returns Array of parsed e-tag references
+     * @deprecated Use getFileETags() instead, which returns all e-tags (not just "script" marker)
+     */
+    getScriptETags(): ETagReference[] {
+        return this.parseETags("script");
+    }
+
+    /**
+     * Get all e-tags from the agent definition.
+     * E-tags may reference kind 1063 (NIP-94 file metadata) events
+     * that contain files bundled with the agent, or other related events.
+     *
+     * Unlike getScriptETags(), this method returns ALL e-tags, not just
+     * those with a specific marker, allowing for general event references.
+     *
+     * @returns Array of parsed e-tag references
+     */
+    getETags(): ETagReference[] {
+        return this.parseETags();
+    }
+
+    /**
+     * Get e-tags with the "file" marker.
+     * These reference kind 1063 (NIP-94 file metadata) events that contain
+     * files bundled with this agent definition.
+     *
+     * @returns Array of parsed e-tag references
+     */
+    getFileETags(): ETagReference[] {
+        return this.parseETags("file");
+    }
+
+    /**
+     * Get e-tags with the "fork" marker.
+     * These reference the source kind 4199 agent definition event that
+     * this agent was forked from.
+     *
+     * @returns Array of parsed e-tag references
+     */
+    getForkETags(): ETagReference[] {
+        return this.parseETags("fork");
+    }
+
+    /**
+     * Get the source agent definition this was forked from (if any).
+     * Returns the first fork e-tag, or undefined if this is not a fork.
+     *
+     * @returns Object with eventId and optional relayUrl, or undefined
+     */
+    getForkSource(): { eventId: string; relayUrl?: string } | undefined {
+        const forks = this.getForkETags();
+        return forks.length > 0 ? forks[0] : undefined;
+    }
+
+    /**
+     * Add a file reference e-tag with the "file" marker.
+     * References a kind 1063 (NIP-94 file metadata) event.
+     *
+     * @param eventId - The event ID of the kind 1063 file metadata event
+     * @param relayUrl - Optional relay hint URL
+     */
+    addFileReference(eventId: string, relayUrl?: string): void {
+        this.tags.push(this.buildETag(eventId, relayUrl, "file"));
+    }
+
+    /**
+     * Set the fork source for this agent definition.
+     * Removes any existing fork e-tags and adds a new one.
+     *
+     * @param eventId - The event ID of the source kind 4199 agent definition
+     * @param relayUrl - Optional relay hint URL
+     */
+    setForkSource(eventId: string, relayUrl?: string): void {
+        // Remove existing fork tags
+        this.tags = this.tags.filter((tag) => !(tag[0] === "e" && tag[3] === "fork"));
+
+        // Add new fork tag
+        this.tags.push(this.buildETag(eventId, relayUrl, "fork"));
+    }
+
+    /**
+     * Build an e-tag tuple with the standard format: ["e", eventId, relayUrl, marker]
+     *
+     * @param eventId - The event ID to reference
+     * @param relayUrl - Optional relay hint URL (defaults to empty string if not provided)
+     * @param marker - The marker for the e-tag (e.g., "file", "fork", "script")
+     * @returns The constructed e-tag tuple
+     */
+    private buildETag(eventId: string, relayUrl: string | undefined, marker: string): ETag {
+        return ["e", eventId, relayUrl ?? "", marker];
+    }
+
+    /**
+     * Parse e-tags from the event, optionally filtering by marker.
+     * Consolidates the common filter/map logic for e-tag extraction.
+     *
+     * @param marker - Optional marker to filter by (e.g., "file", "fork", "script").
+     *                 If not provided, returns all e-tags.
+     * @returns Array of parsed e-tag references with eventId, relayUrl, and marker
+     */
+    private parseETags(marker?: string): ETagReference[] {
+        return this.tags
+            .filter((tag) => tag[0] === "e" && !!tag[1] && (marker === undefined || tag[3] === marker))
+            .map((tag) => ({
+                eventId: tag[1],
+                relayUrl: tag[2] || undefined,
+                marker: tag[3] || undefined,
+            }));
+    }
+
+    /**
+     * Set an optional tag value with consistent semantics.
+     * Removes any existing tag with the same name, then adds it back only if value is truthy.
+     * This means empty strings, undefined, and null all clear the tag.
+     *
+     * Note: For tags where empty string is a valid value (like the "d" tag for slug),
+     * use direct tag manipulation with `value !== undefined` check instead of this helper.
+     *
+     * @param tagName - The tag name to set
+     * @param value - The value to set, or falsy value to clear the tag
+     */
+    private setOptionalTag(tagName: string, value: string | undefined): void {
+        this.removeTag(tagName);
+        if (value) {
+            this.tags.push([tagName, value]);
+        }
+    }
+}