@tenex-chat/backend 0.9.1

package/src/nostr/AgentPublisher.ts

@@ -0,0 +1,437 @@
+import type { AgentInstance } from "@/agents/types";
+import { NDKKind } from "@/nostr/kinds";
+import { getNDK } from "@/nostr/ndkClient";
+import { PendingDelegationsRegistry, RALRegistry } from "@/services/ral";
+import { logger } from "@/utils/logger";
+import { NDKEvent } from "@nostr-dev-kit/ndk";
+import { trace } from "@opentelemetry/api";
+import { AgentEventEncoder } from "./AgentEventEncoder";
+import { injectTraceContext } from "./trace-context";
+import type {
+    AskConfig,
+    CompletionIntent,
+    ConversationIntent,
+    DelegateConfig,
+    DelegationMarkerIntent,
+    ErrorIntent,
+    EventContext,
+    LessonIntent,
+    ToolUseIntent,
+} from "./types";
+
+/**
+ * Comprehensive publisher for all agent-related Nostr events.
+ * Handles agent creation, responses, completions, and delegations.
+ */
+export class AgentPublisher {
+    private agent: AgentInstance;
+    private encoder: AgentEventEncoder;
+
+    constructor(agent: AgentInstance) {
+        this.agent = agent;
+        this.encoder = new AgentEventEncoder();
+    }
+
+    /**
+     * Consume unreported runtime from RAL and enhance context with it.
+     * This ensures each published event gets the incremental runtime since last publish.
+     *
+     * IMPORTANT: Always consumes from RAL to advance lastReportedRuntime, even when
+     * explicit llmRuntime is provided. This prevents double-counting on subsequent events.
+     */
+    private consumeAndEnhanceContext(context: EventContext): EventContext {
+        const ralRegistry = RALRegistry.getInstance();
+
+        // Always consume to advance lastReportedRuntime (prevents double-counting)
+        const unreportedRuntime = ralRegistry.consumeUnreportedRuntime(
+            this.agent.pubkey,
+            context.conversationId,
+            context.ralNumber
+        );
+
+        // DEBUG: Temporary logging to diagnose llm-runtime issue
+        logger.info("[AgentPublisher.consumeAndEnhanceContext]", {
+            agent: this.agent.slug,
+            pubkey: this.agent.pubkey.substring(0, 8),
+            conv: context.conversationId.substring(0, 8),
+            ral: context.ralNumber,
+            unreportedMs: unreportedRuntime,
+        });
+
+        // If context already has llmRuntime set explicitly, use that value
+        // (but we still consumed above to advance the counter)
+        if (context.llmRuntime !== undefined) {
+            return context;
+        }
+
+        return {
+            ...context,
+            llmRuntime: unreportedRuntime > 0 ? unreportedRuntime : undefined,
+        };
+    }
+
+    /**
+     * Safely publish an event with error handling and comprehensive logging.
+     * Throws an error if no relays accept the event.
+     */
+    private async safePublish(event: NDKEvent, eventType: string): Promise<void> {
+        try {
+            const relaySet = await event.publish();
+
+            // Log relay responses
+            const successRelays: string[] = [];
+            for (const relay of relaySet) {
+                successRelays.push(relay.url);
+                logger.debug(`Relay accepted ${eventType} event`, {
+                    eventId: event.id?.substring(0, 8),
+                    eventType,
+                    relayUrl: relay.url,
+                    agent: this.agent.slug,
+                });
+            }
+
+            // Fail explicitly when no relays accept the event
+            if (successRelays.length === 0) {
+                const error = new Error(
+                    `Event published to 0 relays - all relays rejected the ${eventType} event`
+                );
+                logger.error("Event published to 0 relays", {
+                    eventId: event.id?.substring(0, 8),
+                    eventType,
+                    agent: this.agent.slug,
+                    kind: event.kind,
+                    contentLength: event.content?.length || 0,
+                    tagCount: event.tags?.length || 0,
+                    rawEvent: JSON.stringify(event.rawEvent()),
+                });
+                throw error;
+            }
+
+            logger.info(`Published ${eventType} event to ${successRelays.length} relay(s)`, {
+                eventId: event.id?.substring(0, 8),
+                eventType,
+                agent: this.agent.slug,
+                relays: successRelays,
+            });
+        } catch (error) {
+            logger.error(`Failed to publish ${eventType}`, {
+                error,
+                eventId: event.id?.substring(0, 8),
+                agent: this.agent.slug,
+                kind: event.kind,
+                contentLength: event.content?.length || 0,
+                tagCount: event.tags?.length || 0,
+                rawEvent: JSON.stringify(event.rawEvent()),
+            });
+            throw error;
+        }
+    }
+
+    /**
+     * Add delegation tag to an event, linking it to the parent conversation.
+     * This method is used by delegate() and ask() to establish the parent-child
+     * relationship between conversations.
+     *
+     * @param event - The event to add the delegation tag to
+     * @param context - The event context containing the conversationId
+     * @throws Error if context.conversationId is missing
+     */
+    private addDelegationTag(event: NDKEvent, context: EventContext): void {
+        if (!context.conversationId) {
+            throw new Error("Cannot add delegation tag: conversationId is required in context for delegation events");
+        }
+        event.tags.push(["delegation", context.conversationId]);
+    }
+
+    /**
+     * Publish a completion event.
+     * Creates and publishes a properly tagged completion event with p-tag.
+     * Includes both incremental runtime (llm-runtime) and total runtime (llm-runtime-total).
+     *
+     * DELEGATION CHAIN ROUTING: For conversations with a delegation chain, the completion
+     * is routed to the immediate delegator (second-to-last in chain), not triggeringEvent.pubkey.
+     * The recipient pubkey is pre-resolved by createEventContext (layer 3) and passed via
+     * context.completionRecipientPubkey. This avoids a layer violation - AgentPublisher (layer 2)
+     * cannot import ConversationStore directly.
+     *
+     * RACE CONDITION GUARD: If this conversation was killed via the kill tool,
+     * this method returns undefined instead of publishing. This prevents the scenario
+     * where an agent continues running (e.g., in a long tool execution) after being
+     * killed and then publishes a completion that triggers the parent to process it.
+     */
+    async complete(intent: CompletionIntent, context: EventContext): Promise<NDKEvent | undefined> {
+        const ralRegistry = RALRegistry.getInstance();
+
+        // RACE CONDITION GUARD: Check if this agent+conversation was killed
+        // ISSUE 3 FIX: Using agent-scoped check ensures killing one agent
+        // doesn't suppress completions for other agents in the same conversation.
+        if (ralRegistry.isAgentConversationKilled(this.agent.pubkey, context.conversationId)) {
+            logger.warn("[AgentPublisher.complete] Skipping completion - agent+conversation was killed", {
+                agent: this.agent.slug,
+                agentPubkey: this.agent.pubkey.substring(0, 12),
+                conversationId: context.conversationId.substring(0, 12),
+                ralNumber: context.ralNumber,
+            });
+
+            trace.getActiveSpan()?.addEvent("publisher.completion_skipped_killed", {
+                "agent.slug": this.agent.slug,
+                "agent.pubkey": this.agent.pubkey.substring(0, 12),
+                "conversation.id": context.conversationId.substring(0, 12),
+                "ral.number": context.ralNumber,
+            });
+
+            return undefined;
+        }
+
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+
+        // For completion events, include the total accumulated runtime for the entire RAL
+        // This allows delegation aggregation to get the correct total runtime
+        const totalRuntime = ralRegistry.getAccumulatedRuntime(
+            this.agent.pubkey,
+            context.conversationId,
+            context.ralNumber
+        );
+
+        // completionRecipientPubkey is pre-resolved by createEventContext (layer 3)
+        // from the delegation chain stored in ConversationStore. This avoids a layer
+        // violation - AgentPublisher (layer 2) cannot import ConversationStore directly.
+        const contextWithExtras: EventContext = {
+            ...enhancedContext,
+            llmRuntimeTotal: totalRuntime > 0 ? totalRuntime : undefined,
+        };
+
+        const event = this.encoder.encodeCompletion(intent, contextWithExtras);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "completion");
+
+        return event;
+    }
+
+    /**
+     * Publish a conversation event (mid-loop response without p-tag).
+     * Used when agent has text output but delegations are still pending.
+     */
+    async conversation(intent: ConversationIntent, context: EventContext): Promise<NDKEvent> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const event = this.encoder.encodeConversation(intent, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "conversation");
+
+        return event;
+    }
+
+    /**
+     * Publish a delegation event
+     */
+    async delegate(config: DelegateConfig, context: EventContext): Promise<string> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const ndk = getNDK();
+        const event = new NDKEvent(ndk);
+        event.kind = NDKKind.Text; // kind:1 - unified conversation format
+        event.content = config.content;
+
+        // Add recipient p-tag
+        event.tags.push(["p", config.recipient]);
+
+        // No e-tag: delegation events start separate conversations
+
+        if (config.branch) {
+            event.tags.push(["branch", config.branch]);
+        }
+
+        // Add nudge tags for the delegated agent (deduplicated for robustness)
+        if (config.nudges && config.nudges.length > 0) {
+            const uniqueNudges = [...new Set(config.nudges)];
+            for (const nudgeId of uniqueNudges) {
+                event.tags.push(["nudge", nudgeId]);
+            }
+        }
+
+        // Add standard metadata (project tag, model, cost, execution time, etc)
+        this.encoder.addStandardTags(event, enhancedContext);
+
+        // Forward branch tag from triggering event if not explicitly set
+        if (!config.branch) {
+            this.encoder.forwardBranchTag(event, enhancedContext);
+        }
+
+        // Add delegation tag linking to parent conversation
+        this.addDelegationTag(event, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "delegation");
+
+        // Register with PendingDelegationsRegistry for q-tag correlation
+        PendingDelegationsRegistry.register(this.agent.pubkey, context.conversationId, event.id);
+
+        return event.id;
+    }
+
+    /**
+     * Publish an ask event using the multi-question format.
+     * Returns the published NDKEvent so callers can create a ConversationStore.
+     */
+    async ask(config: AskConfig, context: EventContext): Promise<NDKEvent> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const ndk = getNDK();
+        const event = new NDKEvent(ndk);
+        event.kind = NDKKind.Text; // kind:1 - unified conversation format
+        // Content is just the context (user has no access to conversation history)
+        event.content = config.context;
+
+        // Add title tag
+        event.tags.push(["title", config.title]);
+
+        // Add question/multiselect tags
+        for (const question of config.questions) {
+            if (question.type === "question") {
+                const tag = ["question", question.title, question.question];
+                if (question.suggestions) {
+                    tag.push(...question.suggestions);
+                }
+                event.tags.push(tag);
+            } else if (question.type === "multiselect") {
+                const tag = ["multiselect", question.title, question.question];
+                if (question.options) {
+                    tag.push(...question.options);
+                }
+                event.tags.push(tag);
+            }
+        }
+
+        // Add recipient p-tag
+        event.tags.push(["p", config.recipient]);
+
+        // No e-tag: ask events start separate conversations (like delegate)
+
+        // Add standard metadata (project tag, model, cost, execution time, runtime, etc)
+        this.encoder.addStandardTags(event, enhancedContext);
+
+        // Add ask marker
+        event.tags.push(["ask", "true"]);
+
+        // Add t-tag for ask events
+        event.tags.push(["t", "ask"]);
+
+        // Add delegation tag linking to parent conversation
+        this.addDelegationTag(event, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "ask");
+
+        // Register with PendingDelegationsRegistry for q-tag correlation
+        PendingDelegationsRegistry.register(this.agent.pubkey, enhancedContext.conversationId, event.id);
+
+        return event;
+    }
+
+    /**
+     * Publish a delegation follow-up event
+     */
+    async delegateFollowup(
+        params: {
+            recipient: string;
+            content: string;
+            delegationEventId: string;
+            replyToEventId?: string;
+        },
+        context: EventContext
+    ): Promise<string> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const ndk = getNDK();
+        const event = new NDKEvent(ndk);
+        event.kind = NDKKind.Text; // kind:1 - unified conversation format
+        event.content = params.content;
+
+        // Add recipient p-tag
+        event.tags.push(["p", params.recipient]);
+
+        // Add reference to the original delegation event
+        event.tags.push(["e", params.delegationEventId]);
+
+        // Reply to specific response event if provided (for threading)
+        if (params.replyToEventId) {
+            event.tags.push(["e", params.replyToEventId]);
+        }
+
+        // Add standard metadata (project tag, model, cost, execution time, runtime, etc)
+        this.encoder.addStandardTags(event, enhancedContext);
+
+        // Forward branch tag from triggering event
+        this.encoder.forwardBranchTag(event, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "followup");
+
+        return event.id;
+    }
+
+    /**
+     * Publish an error event.
+     * Creates and publishes an error notification event.
+     */
+    async error(intent: ErrorIntent, context: EventContext): Promise<NDKEvent> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const event = this.encoder.encodeError(intent, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, "error");
+
+        return event;
+    }
+
+    /**
+     * Publish a lesson learned event.
+     */
+    async lesson(intent: LessonIntent, context: EventContext): Promise<NDKEvent> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const lessonEvent = this.encoder.encodeLesson(intent, enhancedContext, this.agent);
+
+        injectTraceContext(lessonEvent);
+        await this.agent.sign(lessonEvent);
+        await this.safePublish(lessonEvent, "lesson");
+
+        return lessonEvent;
+    }
+
+    /**
+     * Publish a tool usage event.
+     * Creates and publishes an event with tool name and output tags.
+     */
+    async toolUse(intent: ToolUseIntent, context: EventContext): Promise<NDKEvent> {
+        const enhancedContext = this.consumeAndEnhanceContext(context);
+        const event = this.encoder.encodeToolUse(intent, enhancedContext);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, `tool:${intent.toolName}`);
+
+        return event;
+    }
+
+    /**
+     * Publish a delegation marker event.
+     * Delegation markers track the lifecycle of delegation conversations.
+     *
+     * Note: This does NOT consume runtime from RAL since markers are not part of
+     * the agent's reasoning/action loop. They are metadata events for tracking.
+     */
+    async delegationMarker(intent: DelegationMarkerIntent): Promise<NDKEvent> {
+        const event = this.encoder.encodeDelegationMarker(intent);
+
+        injectTraceContext(event);
+        await this.agent.sign(event);
+        await this.safePublish(event, `delegation-marker:${intent.status}`);
+
+        return event;
+    }
+}

package/src/nostr/BlossomService.ts

@@ -0,0 +1,226 @@
+/**
+ * BlossomService - Handles Blossom media uploads with Nostr authentication
+ *
+ * This service encapsulates all Blossom upload logic including:
+ * - SHA256 hash calculation
+ * - Kind 24242 authorization event creation and signing
+ * - HTTP upload to Blossom servers
+ *
+ * Centralizes NDK usage in the nostr layer, allowing tools to delegate
+ * Blossom operations without directly importing NDK.
+ */
+
+import * as crypto from "node:crypto";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { logger } from "@/utils/logger";
+import { NDKEvent as NDKEventClass } from "@nostr-dev-kit/ndk";
+
+/**
+ * Minimal signer interface needed for Blossom authentication.
+ * This allows both AgentInstance and ToolAgentInfo to be used.
+ */
+export interface BlossomSigner {
+    sign(event: NDKEvent): Promise<void>;
+}
+
+const UPLOAD_TIMEOUT_MS = 60_000;
+
+/**
+ * Result of a successful Blossom upload
+ */
+export interface BlossomUploadResult {
+    /** URL of the uploaded blob */
+    url: string;
+    /** SHA256 hash of the uploaded data */
+    sha256: string;
+    /** Size in bytes */
+    size: number;
+    /** MIME type (if returned by server) */
+    type?: string;
+    /** Timestamp of upload */
+    uploaded?: number;
+}
+
+/**
+ * Options for uploading to Blossom
+ */
+export interface BlossomUploadOptions {
+    /** Blossom server URL (required - callers must load from config) */
+    serverUrl: string;
+    /** Description for the authorization event content */
+    description?: string;
+}
+
+/**
+ * MIME type to file extension mapping
+ */
+const MIME_TO_EXTENSION: Record<string, string> = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "video/mp4": ".mp4",
+    "video/quicktime": ".mov",
+    "video/x-msvideo": ".avi",
+    "video/webm": ".webm",
+    "audio/mpeg": ".mp3",
+    "audio/wav": ".wav",
+    "application/pdf": ".pdf",
+    "application/json": ".json",
+    "text/plain": ".txt",
+};
+
+/**
+ * Get file extension from MIME type
+ */
+export function getExtensionFromMimeType(mimeType: string): string {
+    return MIME_TO_EXTENSION[mimeType] || "";
+}
+
+/**
+ * Calculate SHA256 hash of data
+ */
+export function calculateSHA256(data: Buffer): string {
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * BlossomService handles uploading media to Blossom servers with Nostr authentication.
+ *
+ * This service:
+ * 1. Calculates SHA256 hash of the data
+ * 2. Creates and signs a kind 24242 authorization event
+ * 3. Uploads the data to the Blossom server
+ * 4. Returns the result with URL and metadata
+ */
+export class BlossomService {
+    private signer: BlossomSigner;
+
+    constructor(signer: BlossomSigner) {
+        this.signer = signer;
+    }
+
+    /**
+     * Upload data to Blossom server with Nostr authentication.
+     *
+     * @param data - The binary data to upload
+     * @param mimeType - MIME type of the data (e.g., "image/png")
+     * @param options - Upload configuration including serverUrl (required)
+     * @returns Upload result with URL and metadata
+     */
+    async upload(
+        data: Buffer,
+        mimeType: string,
+        options: BlossomUploadOptions
+    ): Promise<BlossomUploadResult> {
+        const { serverUrl, description = "Blossom upload" } = options;
+
+        // Calculate hash
+        const sha256Hash = calculateSHA256(data);
+
+        logger.debug("[BlossomService] Preparing upload", {
+            size: data.length,
+            mimeType,
+            sha256: sha256Hash.slice(0, 12) + "...",
+            serverUrl,
+        });
+
+        // Create and sign authorization event
+        const authEvent = await this.createAuthEvent(sha256Hash, description);
+
+        // Upload to server
+        const result = await this.uploadToServer(serverUrl, data, mimeType, authEvent);
+
+        logger.info("[BlossomService] Upload successful", {
+            url: result.url,
+            sha256: result.sha256,
+            size: result.size,
+        });
+
+        return result;
+    }
+
+    /**
+     * Create Blossom authorization event (kind 24242)
+     *
+     * Per Blossom protocol, this event authorizes the upload:
+     * - kind: 24242
+     * - content: description of the upload
+     * - tags: ["t", "upload"], ["x", sha256], ["expiration", timestamp]
+     */
+    private async createAuthEvent(sha256Hash: string, description: string): Promise<NDKEvent> {
+        const event = new NDKEventClass();
+        event.kind = 24242;
+        event.content = description;
+        event.created_at = Math.floor(Date.now() / 1000);
+        event.tags = [
+            ["t", "upload"],
+            ["x", sha256Hash],
+            ["expiration", String(Math.floor(Date.now() / 1000) + 3600)], // 1 hour expiration
+        ];
+
+        await this.signer.sign(event);
+        return event;
+    }
+
+    /**
+     * Upload data to Blossom server
+     */
+    private async uploadToServer(
+        serverUrl: string,
+        data: Buffer,
+        mimeType: string,
+        authEvent: NDKEvent
+    ): Promise<BlossomUploadResult> {
+        // Encode the auth event as base64 for the Authorization header
+        const authHeader = `Nostr ${Buffer.from(JSON.stringify(authEvent.rawEvent())).toString("base64")}`;
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT_MS);
+
+        try {
+            const response = await fetch(`${serverUrl}/upload`, {
+                method: "PUT",
+                headers: {
+                    Authorization: authHeader,
+                    "Content-Type": mimeType,
+                    "Content-Length": String(data.length),
+                },
+                body: data,
+                signal: controller.signal,
+            });
+
+            if (!response.ok) {
+                let errorMessage = `Upload failed with status ${response.status}`;
+                try {
+                    const errorData = (await response.json()) as { message?: string };
+                    if (errorData.message) {
+                        errorMessage = `Upload failed: ${errorData.message}`;
+                    }
+                } catch {
+                    // If parsing JSON fails, use the default error message
+                }
+                throw new Error(errorMessage);
+            }
+
+            const result = (await response.json()) as BlossomUploadResult;
+
+            // Add extension to URL if not present
+            if (result.url && !result.url.match(/\.\w+$/)) {
+                const ext = getExtensionFromMimeType(mimeType);
+                if (ext) {
+                    result.url = result.url + ext;
+                }
+            }
+
+            return result;
+        } catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error(`Upload timed out after ${UPLOAD_TIMEOUT_MS}ms`, { cause: error });
+            }
+            throw error;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}