@tenex-chat/backend 0.9.1

package/src/services/nudge/NudgeService.ts

@@ -0,0 +1,224 @@
+import { getNDK } from "@/nostr";
+import { TagExtractor } from "@/nostr/TagExtractor";
+import { logger } from "@/utils/logger";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { SpanStatusCode, context as otelContext, trace } from "@opentelemetry/api";
+import type { NudgeResult, NudgeToolPermissions, NudgeData } from "./types";
+
+const tracer = trace.getTracer("tenex.nudge-service");
+
+/**
+ * Service for fetching and processing Agent Nudge events (kind:4201)
+ * Single Responsibility: Retrieve nudge content and concatenate for system prompt injection
+ */
+export class NudgeService {
+    private static instance: NudgeService;
+
+    private constructor() {}
+
+    static getInstance(): NudgeService {
+        if (!NudgeService.instance) {
+            NudgeService.instance = new NudgeService();
+        }
+        return NudgeService.instance;
+    }
+
+    /**
+     * Fetch nudge events by IDs and concatenate their content
+     * @param eventIds Array of nudge event IDs to fetch
+     * @returns Concatenated content from all nudges, or empty string if none found
+     */
+    async fetchNudges(eventIds: string[]): Promise<string> {
+        if (eventIds.length === 0) {
+            return "";
+        }
+
+        const span = tracer.startSpan("tenex.nudge.fetch_nudges", {
+            attributes: {
+                "nudge.requested_count": eventIds.length,
+            },
+        }, otelContext.active());
+
+        return otelContext.with(trace.setSpan(otelContext.active(), span), async () => {
+            try {
+                const ndk = getNDK();
+                const nudgeEvents = await ndk.fetchEvents({
+                    ids: eventIds,
+                });
+
+                const nudges = Array.from(nudgeEvents);
+                const concatenated = nudges
+                    .map((nudge) => nudge.content.trim())
+                    .filter((content) => content.length > 0)
+                    .join("\n\n");
+
+                const nudgeTitles = nudges.map((n) => n.tagValue("title") || "untitled").join(", ");
+
+                span.setAttributes({
+                    "nudge.fetched_count": nudges.length,
+                    "nudge.content_length": concatenated.length,
+                    "nudge.titles": nudgeTitles,
+                });
+
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                return concatenated;
+            } catch (error) {
+                span.recordException(error as Error);
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: (error as Error).message,
+                });
+                span.end();
+                return "";
+            }
+        });
+    }
+
+    /**
+     * Fetch a single nudge event by ID
+     * @param eventId The nudge event ID
+     * @returns The nudge event or null if not found
+     */
+    async fetchNudge(eventId: string): Promise<NDKEvent | null> {
+        try {
+            const ndk = getNDK();
+            const events = await ndk.fetchEvents({
+                ids: [eventId],
+            });
+
+            const nudge = Array.from(events).find((event) => event.kind === 4201);
+            return nudge || null;
+        } catch (error) {
+            logger.error("[NudgeService] Failed to fetch nudge", { error, eventId });
+            return null;
+        }
+    }
+
+    /**
+     * Fetch nudge events and extract both content and tool permissions.
+     * This method extracts:
+     * - only-tool tags: Highest priority, replaces ALL tools
+     * - allow-tool tags: Adds tools to agent's default set
+     * - deny-tool tags: Removes tools from agent's default set
+     *
+     * @param eventIds Array of nudge event IDs to fetch
+     * @returns NudgeResult with content and tool permissions
+     */
+    async fetchNudgesWithPermissions(eventIds: string[]): Promise<NudgeResult> {
+        const emptyResult: NudgeResult = {
+            nudges: [],
+            content: "",
+            toolPermissions: {},
+        };
+
+        if (eventIds.length === 0) {
+            return emptyResult;
+        }
+
+        const span = tracer.startSpan("tenex.nudge.fetch_nudges_with_permissions", {
+            attributes: {
+                "nudge.requested_count": eventIds.length,
+            },
+        }, otelContext.active());
+
+        return otelContext.with(trace.setSpan(otelContext.active(), span), async () => {
+            try {
+                const ndk = getNDK();
+                const nudgeEvents = await ndk.fetchEvents({
+                    ids: eventIds,
+                });
+
+                const nudges = Array.from(nudgeEvents);
+
+                // Build nudge data array
+                const nudgeDataArray: NudgeData[] = nudges
+                    .map((nudge) => ({
+                        content: nudge.content.trim(),
+                        title: nudge.tagValue("title") || undefined,
+                    }))
+                    .filter((data) => data.content.length > 0);
+
+                // Concatenate content for backward compatibility
+                const concatenated = nudgeDataArray
+                    .map((data) => data.content)
+                    .join("\n\n");
+
+                // Extract tool permissions from all nudges
+                const toolPermissions = this.extractToolPermissions(nudges);
+
+                const nudgeTitles = nudges.map((n) => n.tagValue("title") || "untitled").join(", ");
+
+                span.setAttributes({
+                    "nudge.fetched_count": nudges.length,
+                    "nudge.content_length": concatenated.length,
+                    "nudge.titles": nudgeTitles,
+                    "nudge.only_tools_count": toolPermissions.onlyTools?.length ?? 0,
+                    "nudge.allow_tools_count": toolPermissions.allowTools?.length ?? 0,
+                    "nudge.deny_tools_count": toolPermissions.denyTools?.length ?? 0,
+                });
+
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+
+                return {
+                    nudges: nudgeDataArray,
+                    content: concatenated,
+                    toolPermissions,
+                };
+            } catch (error) {
+                span.recordException(error as Error);
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: (error as Error).message,
+                });
+                span.end();
+                logger.error("[NudgeService] Failed to fetch nudges with permissions", { error });
+                return emptyResult;
+            }
+        });
+    }
+
+    /**
+     * Extract tool permissions from nudge events.
+     * Collects all only-tool, allow-tool, and deny-tool tags across all nudges.
+     *
+     * @param nudges Array of nudge events
+     * @returns Aggregated tool permissions
+     */
+    private extractToolPermissions(nudges: NDKEvent[]): NudgeToolPermissions {
+        const permissions: NudgeToolPermissions = {};
+
+        const onlyTools: string[] = [];
+        const allowTools: string[] = [];
+        const denyTools: string[] = [];
+
+        for (const nudge of nudges) {
+            // Extract only-tool tags
+            const onlyToolValues = TagExtractor.getTagValues(nudge, "only-tool");
+            onlyTools.push(...onlyToolValues);
+
+            // Extract allow-tool tags
+            const allowToolValues = TagExtractor.getTagValues(nudge, "allow-tool");
+            allowTools.push(...allowToolValues);
+
+            // Extract deny-tool tags
+            const denyToolValues = TagExtractor.getTagValues(nudge, "deny-tool");
+            denyTools.push(...denyToolValues);
+        }
+
+        // Only set arrays if they have values (to keep the object clean)
+        if (onlyTools.length > 0) {
+            // Deduplicate and set
+            permissions.onlyTools = [...new Set(onlyTools)];
+        }
+        if (allowTools.length > 0) {
+            permissions.allowTools = [...new Set(allowTools)];
+        }
+        if (denyTools.length > 0) {
+            permissions.denyTools = [...new Set(denyTools)];
+        }
+
+        return permissions;
+    }
+}

package/src/services/nudge/NudgeWhitelistService.ts

@@ -0,0 +1,382 @@
+import { getNDK } from "@/nostr";
+import { NDKKind } from "@/nostr/kinds";
+import { logger } from "@/utils/logger";
+import type { NDKEvent, NDKSubscription } from "@nostr-dev-kit/ndk";
+import { SpanStatusCode, context as otelContext, trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("tenex.nudge-whitelist-service");
+
+/**
+ * Categorized whitelist item - either a nudge or a skill
+ */
+export interface WhitelistItem {
+    /** The event ID of the whitelisted nudge/skill */
+    eventId: string;
+    /** The kind of the referenced event (4201 for nudge, 4202 for skill) */
+    kind: typeof NDKKind.AgentNudge | typeof NDKKind.AgentSkill;
+    /** The name of the nudge/skill (from title tag) */
+    name?: string;
+    /** Description of the nudge/skill (full content - truncation is done in presentation layer) */
+    description?: string;
+    /** Pubkeys that have whitelisted this item (multiple whitelist events can reference same item) */
+    whitelistedBy: string[];
+}
+
+/**
+ * Cached whitelist data with fetch timestamp
+ */
+interface WhitelistCache {
+    /** Whitelisted nudges (kind:4201) */
+    nudges: WhitelistItem[];
+    /** Whitelisted skills (kind:4202) */
+    skills: WhitelistItem[];
+    /** When this cache was last updated */
+    lastUpdated: number;
+}
+
+const REBUILD_DEBOUNCE_MS = 500;
+const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Service for managing nudge/skill whitelists.
+ *
+ * This service subscribes to kind:14202 events from whitelisted pubkeys,
+ * which are NIP-51-like lists that e-tag nudge (kind:4201) and skill (kind:4202) events.
+ *
+ * The service maintains a cached list of all whitelisted nudges and skills,
+ * categorized by their event kind. Cache is built incrementally as events
+ * stream in from the subscription — initialization never blocks on EOSE.
+ */
+export class NudgeSkillWhitelistService {
+    private static instance: NudgeSkillWhitelistService;
+    private cache: WhitelistCache | null = null;
+    private subscription: NDKSubscription | null = null;
+    private whitelistPubkeys: Set<string> = new Set();
+    private initialized = false;
+
+    /** Latest kind:14202 event per author pubkey (replaceable semantics) */
+    private latestWhitelistEvents: Map<string, NDKEvent> = new Map();
+    /** Fetched nudge/skill events by ID — avoids re-fetching */
+    private referencedEventCache: Map<string, NDKEvent> = new Map();
+    /** Debounce timer for coalescing rapid event bursts */
+    private rebuildTimer: ReturnType<typeof setTimeout> | null = null;
+
+    private constructor() {}
+
+    static getInstance(): NudgeSkillWhitelistService {
+        if (!NudgeSkillWhitelistService.instance) {
+            NudgeSkillWhitelistService.instance = new NudgeSkillWhitelistService();
+        }
+        return NudgeSkillWhitelistService.instance;
+    }
+
+    /**
+     * Initialize the service with whitelisted pubkeys.
+     * Returns immediately — cache starts empty and populates as events stream in.
+     */
+    initialize(whitelistPubkeys: string[]): void {
+        if (this.initialized && this.pubkeysMatch(whitelistPubkeys)) {
+            logger.debug("[NudgeSkillWhitelistService] Already initialized with same pubkeys, skipping");
+            return;
+        }
+
+        this.whitelistPubkeys = new Set(whitelistPubkeys);
+        this.initialized = true;
+        this.cache = { nudges: [], skills: [], lastUpdated: Date.now() };
+
+        this.startSubscription();
+
+        logger.info("[NudgeSkillWhitelistService] Initialized", {
+            pubkeyCount: whitelistPubkeys.length,
+        });
+    }
+
+    /**
+     * Check if the given pubkeys match the currently configured whitelist
+     */
+    private pubkeysMatch(newPubkeys: string[]): boolean {
+        if (newPubkeys.length !== this.whitelistPubkeys.size) return false;
+        return newPubkeys.every(pk => this.whitelistPubkeys.has(pk));
+    }
+
+    /**
+     * Start a subscription to kind:14202 events from whitelisted pubkeys.
+     * Updates the cache incrementally as events arrive.
+     */
+    private startSubscription(): void {
+        if (this.subscription) {
+            this.subscription.stop();
+        }
+
+        if (this.whitelistPubkeys.size === 0) {
+            logger.debug("[NudgeSkillWhitelistService] No whitelisted pubkeys, skipping subscription");
+            return;
+        }
+
+        const ndk = getNDK();
+        const authors = Array.from(this.whitelistPubkeys);
+
+        this.subscription = ndk.subscribe(
+            {
+                kinds: [NDKKind.NudgeSkillWhitelist],
+                authors,
+            },
+            {
+                closeOnEose: false,
+                onEvent: (event: NDKEvent) => {
+                    this.handleWhitelistEvent(event);
+                },
+            }
+        );
+
+        logger.debug("[NudgeSkillWhitelistService] Started subscription", {
+            pubkeyCount: authors.length,
+        });
+    }
+
+    /**
+     * Handle an incoming whitelist event. Applies replaceable semantics
+     * (only the latest event per author is kept) and schedules a debounced cache rebuild.
+     */
+    private handleWhitelistEvent(event: NDKEvent): void {
+        const existing = this.latestWhitelistEvents.get(event.pubkey);
+        if (existing && existing.created_at !== undefined && event.created_at !== undefined
+            && existing.created_at >= event.created_at) {
+            return;
+        }
+
+        logger.debug("[NudgeSkillWhitelistService] Received whitelist event", {
+            eventId: event.id?.substring(0, 12),
+            author: event.pubkey.substring(0, 8),
+        });
+
+        this.latestWhitelistEvents.set(event.pubkey, event);
+        this.scheduleRebuild();
+    }
+
+    /**
+     * Schedule a debounced cache rebuild. Coalesces rapid event bursts
+     * (e.g. the initial subscription replay) into a single rebuild.
+     */
+    private scheduleRebuild(): void {
+        if (this.rebuildTimer) {
+            clearTimeout(this.rebuildTimer);
+        }
+        this.rebuildTimer = setTimeout(() => {
+            this.rebuildTimer = null;
+            this.rebuildCache().catch(error => {
+                logger.error("[NudgeSkillWhitelistService] Failed to rebuild cache", { error });
+            });
+        }, REBUILD_DEBOUNCE_MS);
+    }
+
+    /**
+     * Rebuild the cache from all stored whitelist events.
+     * Fetches any referenced nudge/skill events not yet in the local cache.
+     */
+    private async rebuildCache(): Promise<void> {
+        const span = tracer.startSpan("tenex.nudge-whitelist.rebuild", {
+            attributes: {
+                "whitelist.pubkey_count": this.whitelistPubkeys.size,
+            },
+        }, otelContext.active());
+
+        return otelContext.with(trace.setSpan(otelContext.active(), span), async () => {
+            try {
+                if (this.latestWhitelistEvents.size === 0) {
+                    this.cache = { nudges: [], skills: [], lastUpdated: Date.now() };
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return;
+                }
+
+                // Collect all e-tagged event IDs and track whitelisters per event
+                const eventToWhitelisters: Map<string, Set<string>> = new Map();
+
+                for (const event of this.latestWhitelistEvents.values()) {
+                    const eTags = event.tags.filter(tag => tag[0] === "e" && tag[1]);
+                    for (const eTag of eTags) {
+                        const eventId = eTag[1];
+                        if (!eventToWhitelisters.has(eventId)) {
+                            eventToWhitelisters.set(eventId, new Set());
+                        }
+                        eventToWhitelisters.get(eventId)!.add(event.pubkey);
+                    }
+                }
+
+                if (eventToWhitelisters.size === 0) {
+                    this.cache = { nudges: [], skills: [], lastUpdated: Date.now() };
+                    span.setAttributes({ "whitelist.item_count": 0 });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return;
+                }
+
+                // Find IDs not yet in our local cache
+                const unfetchedIds: string[] = [];
+                for (const id of eventToWhitelisters.keys()) {
+                    if (!this.referencedEventCache.has(id)) {
+                        unfetchedIds.push(id);
+                    }
+                }
+
+                // Batch-fetch unfetched events with a timeout
+                if (unfetchedIds.length > 0) {
+                    try {
+                        const ndk = getNDK();
+                        const fetchPromise = ndk.fetchEvents({ ids: unfetchedIds });
+                        const timeoutPromise = new Promise<Set<NDKEvent>>((_, reject) =>
+                            setTimeout(() => reject(new Error("fetchEvents timeout")), FETCH_TIMEOUT_MS)
+                        );
+
+                        const fetched = await Promise.race([fetchPromise, timeoutPromise]);
+                        for (const event of fetched) {
+                            this.referencedEventCache.set(event.id, event);
+                        }
+                    } catch (error) {
+                        logger.warn("[NudgeSkillWhitelistService] Fetch timed out or failed, using cached events", {
+                            unfetchedCount: unfetchedIds.length,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+
+                // Build cache from referencedEventCache + whitelister tracking
+                const nudges: WhitelistItem[] = [];
+                const skills: WhitelistItem[] = [];
+
+                for (const [eventId, whitelisters] of eventToWhitelisters) {
+                    const event = this.referencedEventCache.get(eventId);
+                    if (!event) continue;
+
+                    const whitelistedBy = Array.from(whitelisters);
+
+                    if (event.kind === NDKKind.AgentNudge) {
+                        nudges.push({
+                            eventId: event.id,
+                            kind: NDKKind.AgentNudge,
+                            name: event.tagValue("title") || event.tagValue("name"),
+                            description: event.content,
+                            whitelistedBy,
+                        });
+                    } else if (event.kind === NDKKind.AgentSkill) {
+                        skills.push({
+                            eventId: event.id,
+                            kind: NDKKind.AgentSkill,
+                            name: event.tagValue("title") || event.tagValue("name"),
+                            description: event.content,
+                            whitelistedBy,
+                        });
+                    }
+                }
+
+                this.cache = {
+                    nudges,
+                    skills,
+                    lastUpdated: Date.now(),
+                };
+
+                span.setAttributes({
+                    "whitelist.nudge_count": nudges.length,
+                    "whitelist.skill_count": skills.length,
+                    "whitelist.item_count": nudges.length + skills.length,
+                });
+
+                logger.info("[NudgeSkillWhitelistService] Cache rebuilt", {
+                    nudgeCount: nudges.length,
+                    skillCount: skills.length,
+                });
+
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+            } catch (error) {
+                span.recordException(error as Error);
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: (error as Error).message,
+                });
+                span.end();
+                logger.error("[NudgeSkillWhitelistService] Failed to rebuild cache", { error });
+            }
+        });
+    }
+
+    /**
+     * Get all whitelisted nudges
+     */
+    getWhitelistedNudges(): WhitelistItem[] {
+        if (!this.initialized) {
+            logger.warn("[NudgeSkillWhitelistService] getWhitelistedNudges called before initialize() — returning empty list");
+        }
+        return this.cache?.nudges || [];
+    }
+
+    /**
+     * Get all whitelisted skills
+     */
+    getWhitelistedSkills(): WhitelistItem[] {
+        if (!this.initialized) {
+            logger.warn("[NudgeSkillWhitelistService] getWhitelistedSkills called before initialize() — returning empty list");
+        }
+        return this.cache?.skills || [];
+    }
+
+    /**
+     * Get all whitelisted items (both nudges and skills)
+     */
+    getAllWhitelistedItems(): WhitelistItem[] {
+        if (!this.initialized) {
+            logger.warn("[NudgeSkillWhitelistService] getAllWhitelistedItems called before initialize() — returning empty list");
+        }
+        if (!this.cache) return [];
+        return [...this.cache.nudges, ...this.cache.skills];
+    }
+
+    /**
+     * Check if a nudge event ID is whitelisted
+     */
+    isNudgeWhitelisted(eventId: string): boolean {
+        return this.cache?.nudges.some(n => n.eventId === eventId) || false;
+    }
+
+    /**
+     * Check if a skill event ID is whitelisted
+     */
+    isSkillWhitelisted(eventId: string): boolean {
+        return this.cache?.skills.some(s => s.eventId === eventId) || false;
+    }
+
+    /**
+     * Get a whitelisted nudge by event ID
+     */
+    getNudge(eventId: string): WhitelistItem | undefined {
+        return this.cache?.nudges.find(n => n.eventId === eventId);
+    }
+
+    /**
+     * Get the last cache update time
+     */
+    getLastUpdated(): number | null {
+        return this.cache?.lastUpdated || null;
+    }
+
+    /**
+     * Stop the subscription and clear all state.
+     * Used for cleanup during tests or shutdown.
+     */
+    shutdown(): void {
+        if (this.subscription) {
+            this.subscription.stop();
+            this.subscription = null;
+        }
+        if (this.rebuildTimer) {
+            clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = null;
+        }
+        this.cache = null;
+        this.initialized = false;
+        this.whitelistPubkeys.clear();
+        this.latestWhitelistEvents.clear();
+        this.referencedEventCache.clear();
+    }
+}

package/src/services/nudge/index.ts

@@ -0,0 +1,5 @@
+export { NudgeService } from "./NudgeService";
+export { NudgeSkillWhitelistService, NudgeSkillWhitelistService as NudgeWhitelistService } from "./NudgeWhitelistService";
+export type { NudgeToolPermissions, NudgeResult, NudgeData } from "./types";
+export type { WhitelistItem } from "./NudgeWhitelistService";
+export { isOnlyToolMode, hasToolPermissions } from "./types";

package/src/services/nudge/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Nudge Tool Permissions Types
+ *
+ * Defines the structure for tool permissions specified in nudge events (kind:4201).
+ * Nudges can modify an agent's available tools through three tag types:
+ *
+ * 1. only-tool: Highest priority - REPLACES all tools with only these
+ * 2. allow-tool: Adds tools to the agent's default set
+ * 3. deny-tool: Removes tools from the agent's default set
+ *
+ * Precedence: only-tool > allow-tool/deny-tool
+ */
+
+/**
+ * Tool permissions extracted from nudge event tags.
+ * Used to modify an agent's available tools during execution.
+ */
+export interface NudgeToolPermissions {
+    /**
+     * If set, the agent gets EXACTLY these tools (and nothing else).
+     * This is the highest priority - completely overrides allow/deny and agent defaults.
+     * Tag format: ["only-tool", "tool_name"]
+     */
+    onlyTools?: string[];
+
+    /**
+     * Tools to enable (add to agent's default set).
+     * Ignored if onlyTools is set.
+     * Tag format: ["allow-tool", "tool_name"]
+     */
+    allowTools?: string[];
+
+    /**
+     * Tools to disable (remove from agent's default set).
+     * Ignored if onlyTools is set.
+     * Tag format: ["deny-tool", "tool_name"]
+     */
+    denyTools?: string[];
+}
+
+/**
+ * Individual nudge data with content and title
+ */
+export interface NudgeData {
+    /** The nudge content/prompt */
+    content: string;
+    /** The nudge title (from "title" tag) */
+    title?: string;
+}
+
+/**
+ * Result from fetching nudges with their tool permissions.
+ * Contains both the concatenated content for system prompt injection
+ * and the extracted tool permissions.
+ */
+export interface NudgeResult {
+    /** Individual nudge data for rendering in the fragment */
+    nudges: NudgeData[];
+
+    /** Concatenated content from all nudges (for backward compatibility) */
+    content: string;
+
+    /** Tool permissions extracted from all nudge tags */
+    toolPermissions: NudgeToolPermissions;
+}
+
+/**
+ * Check if nudge permissions are using only-tool mode (highest priority)
+ */
+export function isOnlyToolMode(permissions: NudgeToolPermissions): boolean {
+    return Array.isArray(permissions.onlyTools) && permissions.onlyTools.length > 0;
+}
+
+/**
+ * Check if nudge permissions have any tool modifications
+ */
+export function hasToolPermissions(permissions: NudgeToolPermissions): boolean {
+    return (
+        isOnlyToolMode(permissions) ||
+        (Array.isArray(permissions.allowTools) && permissions.allowTools.length > 0) ||
+        (Array.isArray(permissions.denyTools) && permissions.denyTools.length > 0)
+    );
+}