@tenex-chat/backend 0.9.1

package/src/services/dispatch/AgentRouter.ts

@@ -0,0 +1,181 @@
+import type { AgentInstance } from "@/agents/types";
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import { AgentEventDecoder } from "@/nostr/AgentEventDecoder";
+import type { ProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import chalk from "chalk";
+import type { DelegationCompletionResult } from "./DelegationCompletionHandler";
+
+/**
+ * AgentRouter is a static utility class that determines which agent
+ * should handle an incoming event. This centralizes the routing logic
+ * that was previously embedded in reply.ts.
+ */
+
+// biome-ignore lint/complexity/noStaticOnlyClass: <explanation>
+export class AgentRouter {
+    /**
+     * Process a stop signal (kind 24134) to block an agent in a conversation.
+     * Returns { blocked: true } if the agent was blocked.
+     */
+    static processStopSignal(
+        event: NDKEvent,
+        conversation: ConversationStore,
+        projectContext: ProjectContext
+    ): { blocked: boolean } {
+        const pTags = event.getMatchingTags("p");
+
+        for (const [, agentPubkey] of pTags) {
+            const agent = projectContext.getAgentByPubkey(agentPubkey);
+            if (agent) {
+                conversation.blockAgent(agentPubkey);
+                logger.info(
+                    chalk.yellow(
+                        `Blocked agent ${agent.slug} in conversation ${conversation.id.substring(0, 8)}`
+                    )
+                );
+            }
+        }
+
+        return { blocked: pTags.length > 0 };
+    }
+
+    /**
+     * Determine which agents should handle the event based on p-tags,
+     * event author, and other context.
+     *
+     * @param event - The incoming event
+     * @param projectContext - Project context with agent information
+     * @param conversation - Optional conversation to check for blocked agents
+     * @returns Array of target agents that should process this event
+     */
+    static resolveTargetAgents(
+        event: NDKEvent,
+        projectContext: ProjectContext,
+        conversation?: ConversationStore
+    ): AgentInstance[] {
+        const mentionedPubkeys = AgentEventDecoder.getMentionedPubkeys(event);
+
+        // Check if the event author is an agent in the system
+        const isAuthorAnAgent = AgentEventDecoder.isEventFromAgent(event, projectContext.agents);
+
+        // Check for p-tagged agents regardless of sender
+        if (mentionedPubkeys.length > 0) {
+            // Find ALL p-tagged system agents
+            const targetAgents: AgentInstance[] = [];
+            for (const pubkey of mentionedPubkeys) {
+                // Skip blocked agents
+                if (conversation?.isAgentBlocked(pubkey)) {
+                    const agent = projectContext.getAgentByPubkey(pubkey);
+                    logger.info(
+                        chalk.yellow(
+                            `Skipping blocked agent ${agent?.slug ?? pubkey.substring(0, 8)} in conversation ${conversation.id.substring(0, 8)}`
+                        )
+                    );
+                    continue;
+                }
+
+                const agent = projectContext.getAgentByPubkey(pubkey);
+                if (agent) {
+                    targetAgents.push(agent);
+                }
+            }
+
+            if (targetAgents.length > 0) {
+                const agentNames = targetAgents.map((a) => a.name).join(", ");
+                logger.info(
+                    chalk.gray(`Routing to ${targetAgents.length} p-tagged agent(s): ${agentNames}`)
+                );
+                return targetAgents;
+            }
+        }
+
+        // If no p-tags, don't route to anyone - just log it
+        if (mentionedPubkeys.length === 0) {
+            const senderType = isAuthorAnAgent ? "agent" : "user";
+            logger.info(
+                chalk.gray(
+                    `Event from ${senderType} ${event.pubkey.substring(0, 8)} without p-tags - not routing to any agent`
+                )
+            );
+            return [];
+        }
+
+        return [];
+    }
+
+    /**
+     * Unblock an agent in a conversation if the sender is whitelisted.
+     * Returns { unblocked: true } if successful.
+     */
+    static unblockAgent(
+        event: NDKEvent,
+        conversation: ConversationStore,
+        projectContext: ProjectContext,
+        whitelist: Set<string>
+    ): { unblocked: boolean } {
+        // Only whitelisted pubkeys can unblock
+        if (!whitelist.has(event.pubkey)) {
+            return { unblocked: false };
+        }
+
+        const pTags = event.getMatchingTags("p");
+        let unblocked = false;
+
+        for (const [, agentPubkey] of pTags) {
+            if (conversation.isAgentBlocked(agentPubkey)) {
+                conversation.unblockAgent(agentPubkey);
+                const agent = projectContext.getAgentByPubkey(agentPubkey);
+                logger.info(
+                    chalk.green(
+                        `Unblocked agent ${agent?.slug ?? agentPubkey.substring(0, 8)} in conversation ${conversation.id.substring(0, 8)} by ${event.pubkey.substring(0, 8)}`
+                    )
+                );
+                unblocked = true;
+            }
+        }
+
+        return { unblocked };
+    }
+
+    /**
+     * Resolve routing target for a delegation completion.
+     * Returns the agent and conversation ID where the waiting RAL lives,
+     * or null if the delegation wasn't recorded or agent not found.
+     */
+    static resolveDelegationTarget(
+        delegationResult: DelegationCompletionResult,
+        projectContext: ProjectContext
+    ): { agent: AgentInstance; conversationId: string } | null {
+        if (!delegationResult.recorded) {
+            return null;
+        }
+
+        const { agentSlug, conversationId } = delegationResult;
+        if (!agentSlug || !conversationId) {
+            logger.warn(
+                chalk.yellow(
+                    "[AgentRouter] Delegation recorded but missing agentSlug or conversationId"
+                )
+            );
+            return null;
+        }
+
+        const waitingAgent = projectContext.getAgent(agentSlug);
+        if (!waitingAgent) {
+            logger.warn(
+                chalk.yellow(`[AgentRouter] Waiting agent not found: ${agentSlug}`)
+            );
+            return null;
+        }
+
+        logger.info(
+            chalk.gray(
+                `Routing delegation completion to ${agentSlug} in conversation ${conversationId.substring(0, 8)}`
+            )
+        );
+
+        return { agent: waitingAgent, conversationId };
+    }
+}

package/src/services/dispatch/DelegationCompletionHandler.ts

@@ -0,0 +1,232 @@
+import { TagExtractor } from "@/nostr/TagExtractor";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import { shortenConversationId } from "@/utils/conversation-id";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { RALRegistry } from "@/services/ral";
+import { ConversationStore } from "@/conversations/ConversationStore";
+import { trace, SpanStatusCode, context as otelContext } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("tenex.delegation");
+
+export interface DelegationCompletionResult {
+    /** Whether a completion was recorded */
+    recorded: boolean;
+    /** The agent slug that's waiting for this delegation (if any) */
+    agentSlug?: string;
+    /** The conversation ID where the delegation was made */
+    conversationId?: string;
+    /** Number of pending delegations remaining */
+    pendingCount?: number;
+}
+
+/**
+ * Record a delegation completion event in RALRegistry.
+ * Does NOT handle routing or resumption - that's handled by normal routing + AgentExecutor.
+ *
+ * Flow:
+ * 1. Find which delegation this responds to (via e-tag)
+ * 2. Look up which RAL is waiting for this delegation
+ * 3. Record the completion
+ */
+export async function handleDelegationCompletion(
+    event: NDKEvent
+): Promise<DelegationCompletionResult> {
+    // Early exit: check for e-tags BEFORE creating a span to avoid trace noise
+    // Events without e-tags cannot be delegation completions
+    const eTags = TagExtractor.getETags(event);
+    if (eTags.length === 0) {
+        return { recorded: false };
+    }
+
+    const span = tracer.startSpan("tenex.delegation.completion_check", {
+        attributes: {
+            "event.id": event.id || "",
+            "event.pubkey": event.pubkey,
+            "event.kind": event.kind || 0,
+            "delegation.etag_count": eTags.length,
+        },
+    }, otelContext.active());
+
+    try {
+        const ralRegistry = RALRegistry.getInstance();
+
+        // Try e-tags in reverse order (last to first) as per NIP-10 convention
+        // The last e-tag is typically the direct reply target in threaded conversations
+        let location = null;
+        let delegationEventId = null;
+
+        for (let i = eTags.length - 1; i >= 0; i--) {
+            const eTag = eTags[i];
+            span.addEvent("trying_delegation_etag", {
+                "delegation.event_id": eTag,
+                "etag.index": i,
+            });
+
+            // Look up the pending delegation to get context for validation
+            const pendingInfo = ralRegistry.findDelegation(eTag);
+
+            if (!pendingInfo?.pending) {
+                // No pending delegation found for this e-tag, try next one
+                span.addEvent("no_pending_delegation", {
+                    "delegation.event_id": eTag,
+                });
+                continue;
+            }
+
+            // Validate that the event author is the delegated agent
+            // This prevents OTHER agents from falsely completing delegations
+            if (event.pubkey !== pendingInfo.pending.recipientPubkey) {
+                span.addEvent("completion_sender_mismatch", {
+                    "delegation.event_id": eTag,
+                    "expected.recipient_pubkey": pendingInfo.pending.recipientPubkey.substring(0, 12),
+                    "actual.sender_pubkey": event.pubkey.substring(0, 12),
+                    "validation.matched": false,
+                });
+                logger.debug("[handleDelegationCompletion] Ignoring event - sender is not the delegated agent", {
+                    delegationEventId: eTag.substring(0, 8),
+                    expectedRecipient: pendingInfo.pending.recipientPubkey.substring(0, 12),
+                    actualSender: event.pubkey.substring(0, 12),
+                });
+                continue; // Skip to next e-tag
+            }
+
+            span.addEvent("completion_sender_validated", {
+                "delegation.event_id": eTag,
+                "expected.recipient_pubkey": pendingInfo.pending.recipientPubkey.substring(0, 12),
+                "actual.sender_pubkey": event.pubkey.substring(0, 12),
+                "validation.matched": true,
+            });
+
+            // DEFENSE-IN-DEPTH: Early exit for killed delegations.
+            // The authoritative check is in RALRegistry.recordCompletion(), but we check
+            // here too using the isDelegationKilled() helper to avoid unnecessary work.
+            if (ralRegistry.isDelegationKilled(eTag)) {
+                span.addEvent("completion_skipped_delegation_killed", {
+                    "delegation.event_id": eTag,
+                    "delegation.killed_at": pendingInfo.pending.killedAt,
+                });
+                logger.info("[handleDelegationCompletion] Ignoring completion - delegation was killed", {
+                    delegationEventId: eTag.substring(0, 8),
+                    killedAt: pendingInfo.pending.killedAt,
+                    completionEventId: event.id?.substring(0, 8),
+                });
+                continue; // Skip to next e-tag - this delegation was killed
+            }
+
+            // Record the completion (looks up RAL internally via delegation conversation ID)
+            // NOTE: We no longer build/pass fullTranscript here. The marker-based system
+            // (RALResolver + MessageBuilder) reads the conversation transcript directly from
+            // ConversationStore when expanding delegation markers. Storing redundant transcripts
+            // in CompletedDelegation was causing unnecessary memory/disk bloat.
+            const result = ralRegistry.recordCompletion({
+                delegationConversationId: eTag,
+                recipientPubkey: event.pubkey,
+                response: event.content,
+                completedAt: Math.floor(Date.now() / 1000), // Use seconds to match pending markers
+            });
+
+            if (result) {
+                location = result;
+                delegationEventId = eTag;
+
+                // Add the completion event to the delegation conversation store.
+                // This ensures getDelegationMessages() can return the user's response
+                // when building the delegation marker transcript. Without this, ask
+                // conversations would show "transcript unavailable" instead of the
+                // actual user response.
+                // See: naddr1qvzqqqr4gupzqkmm302xww6uyne99rnhl5kjj53wthjypm2qaem9uz9fdf3hzcf0qyghwumn8ghj7ar9dejhstnrdpshgtcq9p382emxd9uz6en0d3kx7am4wqkkjmn2v43hg6t0dckhzat9w4jj6cmvv4shy6twvullqw7x
+                const delegationStore = ConversationStore.get(eTag);
+                if (delegationStore) {
+                    try {
+                        await ConversationStore.addEvent(eTag, event);
+                        span.addEvent("completion_event_added_to_delegation_store", {
+                            "delegation.conversation_id": shortenConversationId(eTag),
+                        });
+                    } catch (addEventError) {
+                        // Don't throw after recordCompletion has already run.
+                        // The completion is recorded - only transcript storage failed.
+                        logger.warn("[handleDelegationCompletion] Failed to add completion event to delegation store", {
+                            delegationEventId: eTag.substring(0, 8),
+                            completionEventId: event.id?.substring(0, 8),
+                            error: addEventError instanceof Error ? addEventError.message : String(addEventError),
+                        });
+                        span.addEvent("completion_event_add_failed", {
+                            "delegation.conversation_id": shortenConversationId(eTag),
+                            "error": addEventError instanceof Error ? addEventError.message : String(addEventError),
+                        });
+                    }
+                }
+
+                break; // Found a matching delegation
+            }
+        }
+
+        if (!location) {
+            span.addEvent("no_waiting_ral", {
+                "delegation.etags_checked": eTags.length,
+                "delegation.first_etag": eTags[0],
+            });
+            span.setStatus({ code: SpanStatusCode.OK });
+            return { recorded: false };
+        }
+
+        span.setAttribute("delegation.event_id", delegationEventId || "unknown");
+
+        // Get the target agent for logging
+        const projectCtx = getProjectContext();
+
+        // Note: We don't spawn an execution here - AgentDispatchService handles that
+        // via delegationTarget detection. This handler just records the completion.
+
+        // Get counts from conversation storage
+        const pendingDelegations = ralRegistry.getConversationPendingDelegations(
+            location.agentPubkey, location.conversationId, location.ralNumber
+        );
+        const completedDelegations = ralRegistry.getConversationCompletedDelegations(
+            location.agentPubkey, location.conversationId, location.ralNumber
+        );
+
+        const targetAgent = projectCtx.getAgentByPubkey(location.agentPubkey);
+        const agentSlug = targetAgent?.slug;
+
+        span.setAttributes({
+            "agent.pubkey": location.agentPubkey,
+            "agent.slug": agentSlug || "unknown",
+            "conversation.id": shortenConversationId(location.conversationId),
+            "delegation.pending_count": pendingDelegations.length,
+            "delegation.completed_count": completedDelegations.length,
+        });
+
+        span.addEvent("completion_recorded", {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            "delegation.event_id": delegationEventId!, // Non-null when location is set
+            "responder.pubkey": event.pubkey,
+            "response.length": event.content?.length || 0,
+        });
+        span.setStatus({ code: SpanStatusCode.OK });
+
+        logger.info("[handleDelegationCompletion] Recorded delegation completion", {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            delegationEventId: delegationEventId!.substring(0, 8),
+            agentSlug,
+            conversationId: location.conversationId.substring(0, 8),
+            completionEventId: event.id?.substring(0, 8),
+            completedCount: completedDelegations.length,
+            pendingCount: pendingDelegations.length,
+        });
+
+        return {
+            recorded: true,
+            agentSlug,
+            conversationId: location.conversationId,
+            pendingCount: pendingDelegations.length,
+        };
+    } catch (error) {
+        span.recordException(error as Error);
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        throw error;
+    } finally {
+        span.end();
+    }
+}

package/src/services/embedding/EmbeddingProvider.ts

@@ -0,0 +1,188 @@
+import { type FeatureExtractionPipeline, type Tensor, pipeline } from "@huggingface/transformers";
+
+export interface EmbeddingProvider {
+    /**
+     * Generate embedding for a single text
+     */
+    embed(text: string): Promise<Float32Array>;
+
+    /**
+     * Generate embeddings for multiple texts
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+
+    /**
+     * Get the dimension of the embeddings
+     */
+    getDimensions(): Promise<number>;
+
+    /**
+     * Get model identifier
+     */
+    getModelId(): string;
+}
+
+/**
+ * Local transformer-based embedding provider using @huggingface/transformers
+ */
+export class LocalTransformerEmbeddingProvider implements EmbeddingProvider {
+    private extractorPipeline: FeatureExtractionPipeline | null = null;
+    private modelId: string;
+    private dimensions: number | null = null;
+    private initializationPromise: Promise<void> | null = null;
+
+    constructor(modelId = "Xenova/all-MiniLM-L6-v2") {
+        this.modelId = modelId;
+        this.initializationPromise = this.initialize();
+    }
+
+    /**
+     * Initialize the provider by generating a test embedding to determine dimensions.
+     * This ensures dimensions are always available after construction completes.
+     */
+    private async initialize(): Promise<void> {
+        try {
+            const pipe = await this.ensurePipeline();
+            const output = await pipe("test", { pooling: "mean", normalize: true });
+            const embedding = this.tensorToFloat32Array(output);
+            this.dimensions = embedding.length;
+        } catch (error) {
+            throw new Error(
+                `Failed to initialize embedding provider: ${
+                    error instanceof Error ? error.message : String(error)
+                }`,
+                { cause: error }
+            );
+        }
+    }
+
+    private tensorToFloat32Array(tensor: Tensor): Float32Array {
+        return tensor.data instanceof Float32Array
+            ? tensor.data
+            : new Float32Array(tensor.data as ArrayLike<number>);
+    }
+
+    private async ensurePipeline(): Promise<FeatureExtractionPipeline> {
+        if (!this.extractorPipeline) {
+            this.extractorPipeline = await pipeline("feature-extraction", this.modelId);
+        }
+        return this.extractorPipeline;
+    }
+
+    public async embed(text: string): Promise<Float32Array> {
+        const embeddings = await this.embedBatch([text]);
+        return embeddings[0];
+    }
+
+    public async embedBatch(texts: string[]): Promise<Float32Array[]> {
+        await this.ensureInitialized();
+        const pipe = await this.ensurePipeline();
+        const results: Float32Array[] = [];
+
+        for (const text of texts) {
+            const output = await pipe(text, { pooling: "mean", normalize: true });
+            results.push(this.tensorToFloat32Array(output));
+        }
+
+        return results;
+    }
+
+    /**
+     * Ensure the provider has completed initialization.
+     * This guarantees dimensions are available before any operations.
+     */
+    private async ensureInitialized(): Promise<void> {
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+            this.initializationPromise = null;
+        }
+    }
+
+    /**
+     * Get embedding dimensions.
+     * Dimensions are guaranteed to be available after initialization completes.
+     */
+    public async getDimensions(): Promise<number> {
+        await this.ensureInitialized();
+
+        if (this.dimensions === null) {
+            throw new Error(
+                "Embedding dimensions not available after initialization. " +
+                    "This indicates a critical initialization failure."
+            );
+        }
+
+        return this.dimensions;
+    }
+
+    public getModelId(): string {
+        return this.modelId;
+    }
+}
+
+/**
+ * OpenAI-compatible embedding provider
+ * Works with OpenAI, OpenRouter, and other OpenAI-compatible APIs
+ */
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    private apiKey: string;
+    private modelId: string;
+    private baseUrl: string;
+    private dimensions: number | null = null;
+
+    constructor(apiKey: string, modelId = "text-embedding-3-small", baseUrl = "https://api.openai.com/v1") {
+        this.apiKey = apiKey;
+        this.modelId = modelId;
+        this.baseUrl = baseUrl.replace(/\/$/, ""); // Remove trailing slash
+    }
+
+    public async embed(text: string): Promise<Float32Array> {
+        const embeddings = await this.embedBatch([text]);
+        return embeddings[0];
+    }
+
+    public async embedBatch(texts: string[]): Promise<Float32Array[]> {
+        const response = await fetch(`${this.baseUrl}/embeddings`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.modelId,
+                input: texts,
+            }),
+        });
+
+        if (!response.ok) {
+            throw new Error(`OpenAI API error: ${response.statusText}`);
+        }
+
+        interface EmbeddingResponse {
+            data: Array<{ embedding: number[] }>;
+        }
+
+        const data = (await response.json()) as EmbeddingResponse;
+
+        const embeddings = data.data.map((item) => new Float32Array(item.embedding));
+
+        // Cache dimensions from first successful response
+        if (this.dimensions === null && embeddings.length > 0) {
+            this.dimensions = embeddings[0].length;
+        }
+
+        return embeddings;
+    }
+
+    public async getDimensions(): Promise<number> {
+        // If we haven't cached dimensions yet, make a test embedding call
+        if (this.dimensions === null) {
+            await this.embed("test");
+        }
+        return this.dimensions!;
+    }
+
+    public getModelId(): string {
+        return this.modelId;
+    }
+}

package/src/services/embedding/index.ts

@@ -0,0 +1,5 @@
+export type { EmbeddingProvider } from "./EmbeddingProvider";
+export {
+    LocalTransformerEmbeddingProvider,
+    OpenAIEmbeddingProvider,
+} from "./EmbeddingProvider";