@tenex-chat/backend 0.9.1

package/src/tools/implementations/learn.ts

@@ -0,0 +1,166 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import type { EventContext, LessonIntent } from "@/nostr/types";
+import { getProjectContext, isProjectContextInitialized } from "@/services/projects";
+import { RAGService } from "@/services/rag/RAGService";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+
+const lessonLearnSchema = z.object({
+    title: z.string().describe("Brief title/description of what this lesson is about"),
+    lesson: z.string().describe("The key insight or lesson learned - be concise and actionable"),
+    detailed: z
+        .string()
+        .optional()
+        .describe("Detailed version with richer explanation when deeper context is needed"),
+    category: z
+        .string()
+        .optional()
+        .describe(
+            "Single category for filing this lesson (e.g., 'architecture', 'debugging', 'user-preferences')"
+        ),
+    hashtags: z
+        .array(z.string())
+        .default([])
+        .describe("Hashtags for easier sorting and discovery (e.g., ['async', 'error-handling'])"),
+});
+
+type LessonLearnInput = z.infer<typeof lessonLearnSchema>;
+type LessonLearnOutput = {
+    message: string;
+    eventId: string;
+    title: string;
+    hasDetailed: boolean;
+};
+
+// Core implementation - extracted from existing execute function
+async function executeLessonLearn(
+    input: LessonLearnInput,
+    context: ToolExecutionContext
+): Promise<LessonLearnOutput> {
+    const { title, lesson, detailed, category, hashtags } = input;
+
+    logger.info("Agent recording new lesson", {
+        agent: context.agent.name,
+        agentPubkey: context.agent.pubkey,
+        title,
+        lessonLength: lesson.length,
+        conversationId: context.conversationId,
+    });
+
+    // Create lesson intent
+    const intent: LessonIntent = {
+        title,
+        lesson,
+        detailed,
+        category,
+        hashtags,
+    };
+
+    // Create event context
+    // Note: encodeLesson only uses addStandardTags which needs model/ralNumber
+    // rootEvent.id is not used by lesson encoding
+    const eventContext: EventContext = {
+        triggeringEvent: context.triggeringEvent,
+        rootEvent: {},
+        conversationId: context.conversationId,
+        model: context.agent.llmConfig,
+        ralNumber: context.ralNumber,
+    };
+
+    // Use shared AgentPublisher instance from context to create and publish the lesson
+    const lessonEvent = await context.agentPublisher.lesson(intent, eventContext);
+
+    // Add lesson to RAG collection for semantic search
+    try {
+        const ragService = RAGService.getInstance();
+
+        // Ensure the lessons collection exists
+        try {
+            await ragService.createCollection("lessons");
+        } catch (error) {
+            // Collection might already exist, which is fine
+            logger.debug("Lessons collection might already exist", { error });
+        }
+
+        // Add the lesson to the RAG collection
+        const lessonContent = detailed || lesson;
+
+        // Get projectId for project-scoped search isolation
+        let projectId: string | undefined;
+        if (isProjectContextInitialized()) {
+            try {
+                projectId = getProjectContext().project.tagId();
+            } catch {
+                // Project context not available - lesson will lack project scoping
+            }
+        }
+
+        await ragService.addDocuments("lessons", [
+            {
+                id: lessonEvent.encode(),
+                content: lessonContent,
+                metadata: {
+                    title,
+                    category,
+                    hashtags: hashtags.length > 0 ? hashtags : undefined,
+                    agentPubkey: context.agent.pubkey,
+                    agentName: context.agent.name,
+                    timestamp: Date.now(),
+                    hasDetailed: !!detailed,
+                    type: "lesson",
+                    ...(projectId && { projectId }),
+                },
+            },
+        ]);
+
+        logger.info("Lesson added to RAG collection", {
+            title,
+            eventId: lessonEvent.encode(),
+            agentName: context.agent.name,
+        });
+    } catch (error) {
+        // Don't fail the tool if RAG integration fails
+        logger.warn("Failed to add lesson to RAG collection", { error, title });
+    }
+
+    const message = `Lesson recorded: "${title}"${detailed ? " (with detailed version)" : ""}\n\nThis lesson will be available in future conversations to help avoid similar issues.`;
+
+    return {
+        message,
+        eventId: lessonEvent.encode(),
+        title,
+        hasDetailed: !!detailed,
+    };
+}
+
+// AI SDK tool factory
+export function createLessonLearnTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description: `Record new lessons and insights for future reference. Use for content ABOUT YOUR BEHAVIOR, such as:
+- Patterns in how you approach tasks
+- Debugging workflows that work well
+- User preferences and communication styles
+- Behavioral adjustments when user requests changes
+- Performance patterns in your tool usage
+- Things to do differently in future work
+
+Use when the user instructs you to remember something about YOUR BEHAVIOR or PREFERENCES, or when the user instructs you to change some behavior. Lessons persist across conversations and help build institutional memory. Include both concise lesson and detailed explanation when complexity warrants it. Categorize and tag appropriately for future discovery. Lessons become immediately available via lesson_get.
+
+**CRITICAL:** Only use this for content ABOUT YOUR BEHAVIOR. For content about the project itself, use report_write instead.
+
+**NEVER use for:**
+- Project conventions or patterns
+- Architecture documentation
+- Technical specifications
+- Design decisions
+- API documentation
+- Any content that would help others understand the project
+
+See also: report_write (for project documentation)`,
+        inputSchema: lessonLearnSchema,
+        execute: async (input: LessonLearnInput) => {
+            return await executeLessonLearn(input, context);
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/lesson-formatter.ts

@@ -0,0 +1,38 @@
+import type { NDKAgentLesson } from "@/events/NDKAgentLesson";
+
+/**
+ * Standard output shape for lesson retrieval operations.
+ * Consolidates the lesson data structure to avoid duplication between lesson_get and lessons_list.
+ */
+export type FormattedLessonOutput = {
+    eventId: string;
+    title: string;
+    lesson: string;
+    detailed?: string;
+    category?: string;
+    hashtags?: string[];
+    hasDetailed: boolean;
+};
+
+/**
+ * Formats a lesson into the standard output shape.
+ * Used by both lesson_get and lessons_list to ensure consistent formatting.
+ *
+ * @param lesson - The NDKAgentLesson to format
+ * @param eventId - The event ID (may differ from lesson.id if normalized)
+ * @returns Formatted lesson output
+ */
+export function formatLessonOutput(
+    lesson: NDKAgentLesson,
+    eventId: string
+): FormattedLessonOutput {
+    return {
+        eventId,
+        title: lesson.title || "Untitled",
+        lesson: lesson.lesson || lesson.content,
+        detailed: lesson.detailed,
+        category: lesson.category,
+        hashtags: lesson.hashtags,
+        hasDetailed: !!lesson.detailed,
+    };
+}

package/src/tools/implementations/lesson_delete.ts

@@ -0,0 +1,164 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { getProjectContext } from "@/services/projects";
+import { RAGService } from "@/services/rag/RAGService";
+import { createExpectedError } from "@/tools/utils";
+import { logger } from "@/utils/logger";
+import { normalizeLessonEventId } from "@/utils/nostr-entity-parser";
+import { getNDK } from "@/nostr/ndkClient";
+import { NDKEvent } from "@nostr-dev-kit/ndk";
+import { tool } from "ai";
+import { z } from "zod";
+
+const lessonDeleteSchema = z.object({
+    eventId: z.string().describe(
+        "Nostr event ID of the lesson to delete. Supports full 64-char hex ID, 12-char hex prefix, or NIP-19 formats (note1.../nevent1...)."
+    ),
+    reason: z.string().optional().describe(
+        "Optional reason for deleting the lesson"
+    ),
+});
+
+type LessonDeleteInput = z.infer<typeof lessonDeleteSchema>;
+
+interface LessonDeleteOutput {
+    success: boolean;
+    eventId: string;
+    title: string;
+    message: string;
+}
+
+// Type for expected error results
+type LessonDeleteResult = LessonDeleteOutput | { type: "error-text"; text: string };
+
+/**
+ * Core implementation of lesson deletion functionality.
+ * Uses NIP-09 event deletion to mark the lesson as deleted.
+ */
+async function executeLessonDelete(
+    input: LessonDeleteInput,
+    context: ToolExecutionContext
+): Promise<LessonDeleteResult> {
+    const { eventId: inputEventId, reason } = input;
+
+    const projectContext = getProjectContext();
+
+    // Get all lessons for normalization and lookup
+    const allLessons = projectContext.getAllLessons();
+
+    // Normalize the input to a canonical 64-char hex ID
+    const normalizeResult = normalizeLessonEventId(inputEventId, allLessons);
+    if (!normalizeResult.success) {
+        return createExpectedError(normalizeResult.error);
+    }
+
+    const eventId = normalizeResult.eventId;
+
+    logger.info("🗑️ Agent deleting lesson", {
+        agent: context.agent.name,
+        agentPubkey: context.agent.pubkey,
+        inputEventId,
+        resolvedEventId: eventId,
+        reason,
+        conversationId: context.conversationId,
+    });
+
+    // Find the lesson by event ID - only allow deleting own lessons
+    const agentLessons = projectContext.getLessonsForAgent(context.agent.pubkey);
+    const lesson = agentLessons.find((l) => l.id === eventId);
+
+    if (!lesson) {
+        // Check if the lesson exists but belongs to another agent
+        const globalLesson = allLessons.find((l) => l.id === eventId);
+        if (globalLesson) {
+            return createExpectedError(
+                `Cannot delete lesson "${eventId}": You can only delete your own lessons.`
+            );
+        }
+        return createExpectedError(`No lesson found with event ID: "${eventId}"`);
+    }
+
+    const lessonTitle = lesson.title || "Untitled";
+
+    // Create NIP-09 deletion event manually and sign with agent's signer
+    // We can't use lesson.delete() directly because the lesson's NDK instance
+    // doesn't have the agent's signer attached
+    const ndk = getNDK();
+    const deleteEvent = new NDKEvent(ndk);
+    deleteEvent.kind = 5; // NIP-09 deletion event kind
+    deleteEvent.tags = [["e", eventId]]; // Reference the event being deleted
+    deleteEvent.content = reason || "";
+
+    // Sign with the agent's signer and publish
+    // Per error handling contract: unexpected failures should throw
+    await context.agent.sign(deleteEvent);
+    await deleteEvent.publish();
+
+    logger.info("✅ Lesson deletion event published", {
+        agent: context.agent.name,
+        agentPubkey: context.agent.pubkey,
+        eventId,
+        title: lessonTitle,
+        reason,
+        conversationId: context.conversationId,
+    });
+
+    // Remove from RAG collection
+    try {
+        const ragService = RAGService.getInstance();
+        await ragService.deleteDocumentById("lessons", lesson.encode());
+
+        logger.info("📚 Lesson removed from RAG collection", {
+            eventId,
+            title: lessonTitle,
+            agent: context.agent.name,
+        });
+    } catch (error) {
+        // Don't fail the tool if RAG cleanup fails - the lesson is already deleted
+        logger.warn("Failed to remove lesson from RAG collection", {
+            error,
+            eventId,
+            title: lessonTitle,
+        });
+    }
+
+    // Remove from project context cache (also triggers prompt recompilation)
+    projectContext.removeLesson(context.agent.pubkey, eventId);
+
+    return {
+        success: true,
+        eventId,
+        title: lessonTitle,
+        message: `Lesson "${lessonTitle}" has been deleted${reason ? ` (reason: ${reason})` : ""}.`,
+    };
+}
+
+/**
+ * Create an AI SDK tool for deleting lessons
+ */
+export function createLessonDeleteTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description:
+            "Delete a lesson by its Nostr event ID. This creates a deletion event (NIP-09) " +
+            "to mark the lesson as deleted. Only lessons created by the calling agent can be deleted.\n\n" +
+            "Supports multiple ID formats:\n" +
+            "- Full 64-character hex IDs\n" +
+            "- 12-character hex prefixes\n" +
+            "- NIP-19 formats: note1..., nevent1...\n" +
+            "- nostr: prefixed versions of all the above\n\n" +
+            "Use when a lesson is no longer relevant, contains outdated information, or was recorded in error.",
+        inputSchema: lessonDeleteSchema,
+        execute: async (input: LessonDeleteInput) => {
+            return await executeLessonDelete(input, context);
+        },
+    });
+
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: ({ eventId }: LessonDeleteInput) => {
+            return `Deleting lesson: ${eventId}`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/lesson_get.ts

@@ -0,0 +1,105 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { getProjectContext } from "@/services/projects";
+import type { AISdkTool } from "@/tools/types";
+import { createExpectedError } from "@/tools/utils";
+import { logger } from "@/utils/logger";
+import { normalizeLessonEventId } from "@/utils/nostr-entity-parser";
+import { formatLessonOutput, type FormattedLessonOutput } from "./lesson-formatter";
+import { tool } from "ai";
+import { z } from "zod";
+
+const lessonGetSchema = z.object({
+    eventId: z.string().describe("Nostr event ID of the lesson to retrieve. Supports full 64-char hex ID, 12-char hex prefix, or NIP-19 formats (note1.../nevent1...)."),
+});
+
+type LessonGetInput = z.infer<typeof lessonGetSchema>;
+
+// Type for expected error results
+type LessonGetResult = FormattedLessonOutput | { type: "error-text"; text: string };
+
+// Core implementation - fetches lesson by event ID
+// Returns error-text for expected "not found" conditions
+async function executeLessonGet(
+    input: LessonGetInput,
+    context: ToolExecutionContext
+): Promise<LessonGetResult> {
+    const { eventId: inputEventId } = input;
+
+    const projectContext = getProjectContext();
+
+    // Get all lessons upfront for both normalization fallback and lookup
+    const allLessons = projectContext.getAllLessons();
+
+    // Normalize the input to a canonical 64-char hex ID
+    // Supports: hex IDs, hex prefixes, note1..., nevent1..., nostr: prefixed versions
+    const normalizeResult = normalizeLessonEventId(inputEventId, allLessons);
+    if (!normalizeResult.success) {
+        // Invalid event ID format is an expected user error - return error-text
+        return createExpectedError(normalizeResult.error);
+    }
+
+    const eventId = normalizeResult.eventId;
+
+    logger.info("📖 Agent retrieving lesson by event ID", {
+        agent: context.agent.name,
+        agentPubkey: context.agent.pubkey,
+        inputEventId,
+        resolvedEventId: eventId,
+        conversationId: context.conversationId,
+    });
+
+    // Find lesson by event ID - first try agent-specific, then global
+    const agentLessons = projectContext.getLessonsForAgent(context.agent.pubkey);
+    let lesson = agentLessons.find((l) => l.id === eventId);
+    let isGlobalMatch = false;
+
+    if (!lesson) {
+        // Fall back to global search (in case agent pubkey doesn't match exactly)
+        lesson = allLessons.find((l) => l.id === eventId);
+        isGlobalMatch = true;
+    }
+
+    if (!lesson) {
+        // "Lesson not found" is an expected condition - return error-text
+        return createExpectedError(`No lesson found with event ID: "${eventId}"`);
+    }
+
+    logger.info("✅ Successfully retrieved lesson", {
+        agent: context.agent.name,
+        agentPubkey: context.agent.pubkey,
+        eventId,
+        title: lesson.title,
+        hasDetailed: !!lesson.detailed,
+        source: isGlobalMatch ? "global" : "agent",
+        conversationId: context.conversationId,
+    });
+
+    return formatLessonOutput(lesson, eventId);
+}
+
+// AI SDK tool factory
+export function createLessonGetTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description:
+            "Retrieve a lesson by its Nostr event ID. Supports multiple formats:\n" +
+            "- Full 64-character hex IDs\n" +
+            "- 12-character hex prefixes\n" +
+            "- NIP-19 formats: note1..., nevent1...\n" +
+            "- nostr: prefixed versions of all the above\n\n" +
+            "Returns full lesson content including detailed explanations if available. Use when you need to recall specific knowledge or patterns that have been previously documented.",
+        inputSchema: lessonGetSchema,
+        execute: async (input: LessonGetInput) => {
+            return await executeLessonGet(input, context);
+        },
+    });
+
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: ({ eventId }: LessonGetInput) => {
+            return `Reading lesson: ${eventId}`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/lessons_list.ts

@@ -0,0 +1,153 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import { createExpectedError } from "@/tools/utils";
+import { formatLessonOutput } from "./lesson-formatter";
+import { tool } from "ai";
+import { z } from "zod";
+
+const lessonsListSchema = z.object({
+    agentPubkey: z
+        .string()
+        .optional()
+        .describe(
+            "Optional agent pubkey to filter lessons by. If not provided, returns only your own lessons."
+        ),
+});
+
+type LessonsListInput = z.infer<typeof lessonsListSchema>;
+
+type LessonSummary = {
+    eventId: string;
+    title: string;
+    lesson: string;
+    category?: string;
+    hashtags?: string[];
+    author: string; // Agent slug or pubkey fallback
+    hasDetailed: boolean;
+    createdAt?: number;
+};
+
+type LessonsListOutput = {
+    success: boolean;
+    lessons: LessonSummary[];
+    totalCount: number;
+    agentFilter?: string;
+};
+
+type LessonsListResult = LessonsListOutput | { type: "error-text"; text: string };
+
+/**
+ * Normalizes a pubkey string: trims whitespace and lowercases.
+ * Returns the normalized value, or undefined if input is empty/whitespace.
+ */
+function normalizePubkey(pubkey: string | undefined): string | undefined {
+    if (!pubkey) return undefined;
+    const trimmed = pubkey.trim();
+    if (trimmed === "") return undefined;
+    return trimmed.toLowerCase();
+}
+
+/**
+ * Validates that a string is a valid hex pubkey (64 hex characters).
+ * Returns null if valid, error message if invalid.
+ * Expects pre-normalized input (trimmed, lowercased).
+ */
+function validateAgentPubkey(pubkey: string, originalInput: string): string | null {
+    // Must be exactly 64 hex characters (already lowercased)
+    if (!/^[0-9a-f]{64}$/.test(pubkey)) {
+        return `Invalid agent pubkey format: "${originalInput}". Expected 64-character hex string`;
+    }
+
+    return null;
+}
+
+/**
+ * Core implementation - list lessons for the project
+ */
+async function executeLessonsList(
+    input: LessonsListInput,
+    context: ToolExecutionContext
+): Promise<LessonsListResult> {
+    const { agentPubkey } = input;
+
+    // Normalize the input pubkey once - trim whitespace and lowercase
+    const normalizedInputPubkey = normalizePubkey(agentPubkey);
+
+    // Validate agentPubkey if provided (after normalization)
+    if (agentPubkey !== undefined) {
+        // Check if normalization resulted in empty (whitespace-only input)
+        if (normalizedInputPubkey === undefined) {
+            return createExpectedError("Agent pubkey cannot be empty");
+        }
+        const validationError = validateAgentPubkey(normalizedInputPubkey, agentPubkey);
+        if (validationError) {
+            return createExpectedError(validationError);
+        }
+    }
+
+    // Determine effective pubkey: use normalized input or default to calling agent
+    const effectivePubkey = normalizedInputPubkey ?? context.agent.pubkey;
+
+    logger.info("📚 Listing lessons", {
+        agent: context.agent.name,
+        agentFilter: effectivePubkey,
+        conversationId: context.conversationId,
+    });
+
+    const projectContext = getProjectContext();
+
+    // Get lessons based on filter
+    const rawLessons = projectContext.getLessonsForAgent(effectivePubkey);
+
+    // Transform lessons to summary format
+    const lessons: LessonSummary[] = rawLessons.map((lesson) => {
+        // Try to resolve author pubkey to agent slug (matching reports_list pattern)
+        const agent = projectContext.getAgentByPubkey(lesson.pubkey);
+        const authorSlug = agent?.slug ?? lesson.pubkey;
+
+        // Use shared formatter for consistent lesson formatting
+        const formatted = formatLessonOutput(lesson, lesson.id);
+
+        return {
+            ...formatted,
+            author: authorSlug,
+            createdAt: lesson.created_at,
+        };
+    });
+
+    // Sort by creation date, most recent first
+    lessons.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+
+    logger.info("✅ Lessons listed successfully", {
+        total: lessons.length,
+        agent: context.agent.name,
+        agentFilter: effectivePubkey,
+        conversationId: context.conversationId,
+    });
+
+    return {
+        success: true,
+        lessons,
+        totalCount: lessons.length,
+        agentFilter: effectivePubkey,
+    };
+}
+
+/**
+ * AI SDK tool factory
+ */
+export function createLessonsListTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "List lessons learned by agents in the project. Returns only your own lessons by default, " +
+            "including title, full lesson content, category, hashtags, and author (agent slug). " +
+            "Optionally filter by agent pubkey to see lessons from a specific agent. " +
+            "Results are sorted by creation date (most recent first). Use this to discover what lessons are available. " +
+            "For lessons with detailed explanations, use lesson_get to retrieve the full detailed content.",
+        inputSchema: lessonsListSchema,
+        execute: async (input: LessonsListInput) => {
+            return await executeLessonsList(input, context);
+        },
+    }) as AISdkTool;
+}