@tenex-chat/backend 0.9.1

package/src/nostr/InterventionPublisher.ts

@@ -0,0 +1,132 @@
+import { config } from "@/services/ConfigService";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { logger } from "@/utils/logger";
+import { NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+import { trace } from "@opentelemetry/api";
+import { AgentEventEncoder } from "./AgentEventEncoder";
+import { injectTraceContext } from "./trace-context";
+import type { InterventionReviewIntent } from "./types";
+
+/**
+ * Publisher for intervention review request events.
+ * Uses the backend private key (same as scheduled jobs) for signing.
+ *
+ * This publisher follows the established Nostr event encoding patterns:
+ * - Uses AgentEventEncoder for event creation and tagging
+ * - Injects trace context for observability
+ * - Includes project `a` tag for proper event association
+ */
+export class InterventionPublisher {
+    private signer: NDKPrivateKeySigner | null = null;
+    private encoder: AgentEventEncoder;
+
+    constructor() {
+        this.encoder = new AgentEventEncoder();
+    }
+
+    /**
+     * Initialize the publisher by loading the backend signer.
+     * Must be called before publishing events.
+     */
+    async initialize(): Promise<void> {
+        this.signer = await config.getBackendSigner();
+        logger.debug("InterventionPublisher initialized", {
+            pubkey: this.signer.pubkey.substring(0, 8),
+        });
+    }
+
+    /**
+     * Get the publisher's pubkey (backend key).
+     * Throws if not initialized.
+     */
+    getPubkey(): string {
+        if (!this.signer) {
+            throw new Error("InterventionPublisher not initialized");
+        }
+        return this.signer.pubkey;
+    }
+
+    /**
+     * Publish an intervention review request event.
+     *
+     * Uses AgentEventEncoder to ensure consistent event structure including:
+     * - Project `a` tag for proper event association
+     * - Trace context injection for observability
+     * - Standard intervention-specific tags
+     *
+     * Names are pre-resolved by the caller (InterventionService) before being
+     * passed to this method. This avoids circular dependencies since
+     * InterventionPublisher (nostr layer) cannot import PubkeyService (services layer).
+     *
+     * @param humanReplicaPubkey - Pubkey of the intervention agent to notify
+     * @param conversationId - ID of the original conversation
+     * @param userName - Human-readable name of the user who hasn't responded (pre-resolved)
+     * @param agentName - Human-readable name of the agent that completed work (pre-resolved)
+     * @returns The published event ID
+     */
+    async publishReviewRequest(
+        humanReplicaPubkey: string,
+        conversationId: string,
+        userName: string,
+        agentName: string
+    ): Promise<string> {
+        if (!this.signer) {
+            throw new Error("InterventionPublisher not initialized");
+        }
+
+        const intent: InterventionReviewIntent = {
+            targetPubkey: humanReplicaPubkey,
+            conversationId,
+            userName,
+            agentName,
+        };
+
+        // Use encoder to create properly tagged event
+        const event = this.encoder.encodeInterventionReview(intent);
+
+        // Inject trace context for observability
+        injectTraceContext(event);
+
+        // Sign with backend signer
+        await event.sign(this.signer);
+
+        const shortConversationId = shortenConversationId(conversationId);
+
+        try {
+            const relaySet = await event.publish();
+            const successRelays: string[] = [];
+            for (const relay of relaySet) {
+                successRelays.push(relay.url);
+            }
+
+            if (successRelays.length === 0) {
+                logger.warn("Intervention review request published to 0 relays", {
+                    eventId: event.id?.substring(0, 8),
+                    conversationId: shortConversationId,
+                });
+            } else {
+                logger.info("Published intervention review request", {
+                    eventId: event.id?.substring(0, 8),
+                    conversationId: shortConversationId,
+                    targetAgent: humanReplicaPubkey.substring(0, 8),
+                    relayCount: successRelays.length,
+                });
+            }
+
+            trace.getActiveSpan()?.addEvent("intervention.review_request_published", {
+                "event.id": event.id || "unknown",
+                "conversation.id": conversationId,
+                "target.pubkey": humanReplicaPubkey.substring(0, 8),
+                "relay.count": successRelays.length,
+            });
+
+            return event.id || "";
+        } catch (error) {
+            logger.error("Failed to publish intervention review request", {
+                error,
+                conversationId: shortConversationId,
+            });
+            throw error;
+        }
+    }
+}

package/src/nostr/TagExtractor.ts

@@ -0,0 +1,228 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Utility class for extracting and processing Nostr event tags.
+ * Consolidates tag extraction logic scattered across the codebase.
+ *
+ * This class provides a single source of truth for tag extraction,
+ * replacing 20+ instances of manual tag filtering across files.
+ */
+export class TagExtractor {
+    /**
+     * Extract all a-tags from an event
+     * @param event - The event to extract a-tags from
+     * @returns Array of a-tag values
+     */
+    static getATags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "a")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract project-specific A-tags (those starting with "31933:")
+     * @param event - The event to extract project A-tags from
+     * @returns Array of project A-tag values
+     */
+    static getProjectATags(event: NDKEvent): string[] {
+        return this.getATags(event).filter((tag) => tag.startsWith("31933:"));
+    }
+
+    /**
+     * Extract all E-tags from an event
+     * @param event - The event to extract E-tags from
+     * @returns Array of E-tag values (event IDs)
+     */
+    static getETags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "e")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract the first E-tag value (commonly used for parent event reference)
+     * @param event - The event to extract E-tag from
+     * @returns The first E-tag value or null
+     */
+    static getFirstETag(event: NDKEvent): string | null {
+        const eTags = this.getETags(event);
+        return eTags.length > 0 ? eTags[0] : null;
+    }
+
+    /**
+     * Extract all P-tags from an event
+     * @param event - The event to extract P-tags from
+     * @returns Array of P-tag values (pubkeys)
+     */
+    static getPTags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "p")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract mentioned pubkeys from P-tags (alias for getPTags)
+     * @param event - The event to extract mentioned pubkeys from
+     * @returns Array of mentioned pubkeys
+     */
+    static getMentionedPubkeys(event: NDKEvent): string[] {
+        return this.getPTags(event);
+    }
+
+    /**
+     * Extract tool tags from an event
+     * @param event - The event to extract tool tags from
+     * @returns Array of tool tag objects with name and args
+     */
+    static getToolTags(event: NDKEvent): Array<{ name: string; args?: unknown }> {
+        return event.tags
+            .filter((tag) => tag[0] === "tool")
+            .map((tag) => {
+                const toolInfo: { name: string; args?: unknown } = { name: tag[1] };
+                if (tag[2]) {
+                    try {
+                        toolInfo.args = JSON.parse(tag[2]);
+                    } catch {
+                        // Keep args as undefined if parsing fails
+                    }
+                }
+                return toolInfo;
+            })
+            .filter((tool): tool is { name: string; args?: unknown } => !!tool.name);
+    }
+
+    /**
+     * Extract D-tag value (used for replaceable events)
+     * @param event - The event to extract D-tag from
+     * @returns The D-tag value or null
+     */
+    static getDTag(event: NDKEvent): string | null {
+        const dTag = event.tags.find((tag) => tag[0] === "d");
+        return dTag?.[1] || null;
+    }
+
+    /**
+     * Extract K-tags (kind tags) from an event
+     * @param event - The event to extract K-tags from
+     * @returns Array of K-tag values (kind numbers as strings)
+     */
+    static getKTags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "k")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract mode tags from an event
+     * @param event - The event to extract mode tags from
+     * @returns Array of mode tag values
+     */
+    static getModeTags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "mode")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Check if event has a specific mode tag
+     * @param event - The event to check
+     * @param mode - The mode to check for
+     * @returns True if the event has the specified mode tag
+     */
+    static hasMode(event: NDKEvent, mode: string): boolean {
+        return this.getModeTags(event).includes(mode);
+    }
+
+    /**
+     * Extract nudge tags from an event
+     * @param event - The event to extract nudge tags from
+     * @returns Array of nudge event IDs
+     */
+    static getNudgeTags(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "nudge")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract error type from error tags
+     * @param event - The event to extract error type from
+     * @returns The error type or null
+     */
+    static getErrorType(event: NDKEvent): string | null {
+        const errorTag = event.tags.find((tag) => tag[0] === "error");
+        return errorTag?.[1] || null;
+    }
+
+    /**
+     * Extract moderator from moderator tags
+     * @param event - The event to extract moderator from
+     * @returns The moderator pubkey or null
+     */
+    static getModerator(event: NDKEvent): string | null {
+        const modTag = event.tags.find((tag) => tag[0] === "moderator");
+        return modTag?.[1] || null;
+    }
+
+    /**
+     * Extract participant pubkeys from participant tags
+     * @param event - The event to extract participants from
+     * @returns Array of participant pubkeys
+     */
+    static getParticipants(event: NDKEvent): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === "participant")
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Extract trace context from an event (for telemetry)
+     * @param event - The event to extract trace context from
+     * @returns The trace context value or null
+     */
+    static getTraceContext(event: NDKEvent): string | null {
+        const traceTag = event.tags.find((tag) => tag[0] === "trace_context");
+        return traceTag?.[1] || null;
+    }
+
+    /**
+     * Check if an event has any tags of a specific type
+     * @param event - The event to check
+     * @param tagType - The tag type to check for
+     * @returns True if the event has at least one tag of the specified type
+     */
+    static hasTag(event: NDKEvent, tagType: string): boolean {
+        return event.tags.some((tag) => tag[0] === tagType);
+    }
+
+    /**
+     * Get all values for a specific tag type
+     * @param event - The event to extract tag values from
+     * @param tagType - The tag type to extract
+     * @returns Array of tag values
+     */
+    static getTagValues(event: NDKEvent, tagType: string): string[] {
+        return event.tags
+            .filter((tag) => tag[0] === tagType)
+            .map((tag) => tag[1])
+            .filter((value): value is string => !!value);
+    }
+
+    /**
+     * Get the first value for a specific tag type
+     * @param event - The event to extract tag value from
+     * @param tagType - The tag type to extract
+     * @returns The first tag value or null
+     */
+    static getTagValue(event: NDKEvent, tagType: string): string | null {
+        const values = this.getTagValues(event, tagType);
+        return values.length > 0 ? values[0] : null;
+    }
+}

package/src/nostr/collectEvents.ts

@@ -0,0 +1,83 @@
+import { logger } from "@/utils/logger";
+import type NDK from "@nostr-dev-kit/ndk";
+import type { NDKEvent, NDKFilter, NDKSubscriptionOptions } from "@nostr-dev-kit/ndk";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export interface CollectEventsOptions {
+    /** Additional subscription options (closeOnEose is always forced true). */
+    subOpts?: Omit<NDKSubscriptionOptions, "closeOnEose">;
+    /** Timeout in milliseconds. Defaults to 15 000. Set to 0 to disable. */
+    timeoutMs?: number;
+}
+
+/**
+ * Subscribe to a filter and collect all events until EOSE, with timeout
+ * protection and deduplication by event id.
+ *
+ * Resolves with the collected (deduplicated) events once EOSE is received
+ * or the timeout fires — whichever comes first.  If the relay closes the
+ * connection before EOSE, the partial set is returned and a warning is logged.
+ */
+export function collectEvents(
+    ndk: NDK,
+    filter: NDKFilter,
+    options: CollectEventsOptions = {},
+): Promise<NDKEvent[]> {
+    const { subOpts = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    const seen = new Map<string, NDKEvent>();
+
+    return new Promise<NDKEvent[]>((resolve) => {
+        let settled = false;
+        let eoseReceived = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+
+        const finish = () => {
+            if (settled) return;
+            settled = true;
+            if (timer) clearTimeout(timer);
+            resolve(Array.from(seen.values()));
+        };
+
+        const sub = ndk.subscribe(
+            filter,
+            { ...subOpts, closeOnEose: true },
+            {
+                onEvent: (event) => {
+                    try {
+                        seen.set(event.id, event);
+                    } catch (err) {
+                        logger.warn("collectEvents: error in onEvent", { err });
+                    }
+                },
+                onEose: () => {
+                    eoseReceived = true;
+                    finish();
+                },
+                onClose: () => {
+                    if (!eoseReceived) {
+                        logger.warn("collectEvents: relay closed before EOSE", {
+                            filter,
+                            collected: seen.size,
+                        });
+                    }
+                    finish();
+                },
+            },
+        );
+
+        if (timeoutMs > 0) {
+            timer = setTimeout(() => {
+                if (!settled) {
+                    logger.warn("collectEvents: timed out waiting for EOSE", {
+                        timeoutMs,
+                        filter,
+                        collected: seen.size,
+                    });
+                    sub.stop();
+                    finish();
+                }
+            }, timeoutMs);
+        }
+    });
+}

package/src/nostr/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Nostr event kinds used in the application
+ */
+export enum NostrKind {
+    // Standard kinds
+    TEXT_NOTE = 1,
+    REACTION = 7,
+    ARTICLE = 30023,
+}
+
+/**
+ * Standard Nostr tag names
+ */
+export enum NostrTag {
+    // Standard tags
+    EVENT = "e",
+    PUBKEY = "p",
+    REPLACEABLE = "a",
+
+    // Application-specific tags
+    MODE = "mode",
+    PARTICIPANT = "participant",
+    REASON = "reason",
+    TOOL = "tool",
+}
+
+/**
+ * Tag values for specific application modes
+ */
+export enum TagValue {
+    REACTION_POSITIVE = "+",
+    DELEGATE = "delegate",
+}
+
+/**
+ * Maximum lengths for various fields
+ */
+export const MAX_REASON_LENGTH = 200;

package/src/nostr/encryption.ts

@@ -0,0 +1,26 @@
+/**
+ * NIP-44 encryption/decryption helpers.
+ *
+ * Wraps NDK runtime objects (NDKUser) so that service-layer code
+ * never needs to construct NDK instances directly.
+ */
+
+import { NDKUser } from "@nostr-dev-kit/ndk";
+import type { NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+
+/**
+ * Decrypt NIP-44 encrypted content from a sender.
+ *
+ * @param senderPubkey - Hex pubkey of the sender
+ * @param content - Encrypted content string
+ * @param signer - The private key signer to decrypt with
+ * @returns Decrypted plaintext string
+ */
+export async function nip44Decrypt(
+    senderPubkey: string,
+    content: string,
+    signer: NDKPrivateKeySigner,
+): Promise<string> {
+    const sender = new NDKUser({ pubkey: senderPubkey });
+    return signer.decrypt(sender, content, "nip44");
+}

package/src/nostr/index.ts

@@ -0,0 +1,31 @@
+// Agent event system
+
+export { AgentEventDecoder } from "./AgentEventDecoder";
+
+// Blossom upload service
+export { BlossomService, calculateSHA256, getExtensionFromMimeType } from "./BlossomService";
+export type {
+    BlossomUploadResult,
+    BlossomUploadOptions,
+    BlossomSigner,
+} from "./BlossomService";
+export type {
+    CompletionIntent,
+    DelegationIntent,
+    EventContext,
+} from "./types";
+export { AgentEventEncoder } from "./AgentEventEncoder";
+export { AgentProfilePublisher } from "./AgentProfilePublisher";
+export { AgentPublisher } from "./AgentPublisher";
+export { InterventionPublisher } from "./InterventionPublisher";
+export { injectTraceContext, type EventWithTags } from "./trace-context";
+export { collectEvents } from "./collectEvents";
+export type { CollectEventsOptions } from "./collectEvents";
+export { getNDK } from "./ndkClient";
+export {
+    getAgentSlugFromEvent,
+    isEventFromAgent,
+    isEventFromUser,
+} from "./utils";
+export { pubkeyFromNsec } from "./keys";
+export { nip44Decrypt } from "./encryption";

package/src/nostr/keys.ts

@@ -0,0 +1,17 @@
+/**
+ * Nostr key derivation utilities
+ *
+ * This module provides helpers for working with Nostr keys.
+ * All NDK key operations should be centralized here to maintain architectural boundaries.
+ */
+import { NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+
+/**
+ * Derive a public key from an nsec (private key)
+ * @param nsec - The private key in nsec format
+ * @returns The derived public key
+ */
+export function pubkeyFromNsec(nsec: string): string {
+    const signer = new NDKPrivateKeySigner(nsec);
+    return signer.pubkey;
+}

package/src/nostr/kinds.ts

@@ -0,0 +1,37 @@
+/**
+ * Centralized event kind definitions for TENEX.
+ *
+ * This module extends NDK's NDKKind enum with custom Tenex event kinds.
+ * All kind references throughout the codebase should use this module instead
+ * of importing NDKKind directly or using magic numbers.
+ */
+
+import { NDKKind as BaseNDKKind } from "@nostr-dev-kit/ndk";
+
+// Re-export all base NDK kinds
+export const NDKKind = {
+    ...BaseNDKKind,
+
+    // Standard NIP kinds
+    Text: 1 as BaseNDKKind, // Regular text note (kind:1) - unified conversation format
+    EventMetadata: 513 as BaseNDKKind, // Event metadata (titles, summaries)
+    Comment: 1111 as BaseNDKKind, // NIP-22 Comment - used for lesson refinements
+    AgentLesson: 4129 as BaseNDKKind, // Agent Lesson - learned knowledge
+    AgentDefinition: 4199 as BaseNDKKind, // Agent Definition
+    AgentNudge: 4201 as BaseNDKKind, // Agent Nudge - system prompt injection
+    AgentSkill: 4202 as BaseNDKKind, // Agent Skill - transient capability injection
+    DelegationMarker: 4203 as BaseNDKKind, // Delegation Marker - lifecycle tracking
+    NudgeSkillWhitelist: 14202 as BaseNDKKind, // Nudge/Skill Whitelist - NIP-51-like list of e-tagged nudges/skills
+    ProjectAgentSnapshot: 14199 as BaseNDKKind, // Owner-agent declaration (replaceable, p-tags agents)
+
+    // Tenex custom kinds (2xxxx range)
+    TenexBootProject: 24000 as BaseNDKKind, // Boot project via a-tag
+    TenexProjectStatus: 24010 as BaseNDKKind,
+    TenexAgentConfigUpdate: 24020 as BaseNDKKind,
+    TenexAgentDelete: 24030 as BaseNDKKind, // Agent deletion from projects or globally
+    TenexConfigUpdate: 25000 as BaseNDKKind, // Encrypted config updates (e.g., APNs device tokens)
+    TenexOperationsStatus: 24133 as BaseNDKKind,
+    TenexStopCommand: 24134 as BaseNDKKind,
+} as const;
+
+export type NDKKind = (typeof NDKKind)[keyof typeof NDKKind];

package/src/nostr/ndkClient.ts

@@ -0,0 +1,72 @@
+import { getRelayUrls } from "./relays";
+import { logger } from "@/utils/logger";
+/**
+ * TENEX CLI: NDK Singleton
+ * Manages a single NDK instance for the CLI
+ */
+import NDK from "@nostr-dev-kit/ndk";
+
+let ndk: NDK | undefined;
+
+/**
+ * Initialize NDK with timeout for relay connections
+ * Proceeds even if relay connection fails (daemon can still function locally)
+ */
+export async function initNDK(): Promise<void> {
+    if (ndk) {
+        // Disconnect existing instance
+        if (ndk.pool?.relays) {
+            for (const relay of ndk.pool.relays.values()) {
+                relay.disconnect();
+            }
+        }
+    }
+
+    const relays = getRelayUrls();
+    logger.debug(`Initializing NDK with relays: ${relays.join(", ")}`);
+
+    ndk = new NDK({
+        explicitRelayUrls: [...relays],
+        enableOutboxModel: false,
+        autoConnectUserRelays: true,
+    });
+
+    // Connect with timeout - don't block daemon startup if relays are unreachable
+    const connectionTimeout = 5000; // 5 seconds
+    try {
+        await Promise.race([
+            ndk.connect(),
+            new Promise((_, reject) =>
+                setTimeout(() => reject(new Error("Connection timeout")), connectionTimeout)
+            ),
+        ]);
+        logger.debug("NDK connected to relays");
+    } catch (error) {
+        logger.warn(`NDK relay connection failed or timed out after ${connectionTimeout}ms - continuing without Nostr connectivity`, {
+            error: error instanceof Error ? error.message : String(error),
+            relays,
+        });
+        // Don't throw - daemon can still function locally without Nostr
+    }
+}
+
+export function getNDK(): NDK {
+    if (!ndk) {
+        throw new Error(
+            "NDK not initialized. Please call initNDK() first or check your network configuration."
+        );
+    }
+    return ndk;
+}
+
+export async function shutdownNDK(): Promise<void> {
+    if (ndk) {
+        // Disconnect all relays
+        if (ndk.pool?.relays) {
+            for (const relay of ndk.pool.relays.values()) {
+                relay.disconnect();
+            }
+        }
+        ndk = undefined;
+    }
+}