@tenex-chat/backend 0.9.1

package/src/tools/implementations/report_read.ts

@@ -0,0 +1,160 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { getLocalReportStore, InvalidSlugError } from "@/services/reports";
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+import { nip19 } from "nostr-tools";
+
+const reportReadSchema = z.object({
+    identifier: z
+        .string()
+        .describe("The report identifier - can be a slug (e.g., 'my-report'), an naddr (e.g., 'naddr1...'), or a nostr: URI (e.g., 'nostr:naddr1...')"),
+});
+
+type ReportReadInput = z.infer<typeof reportReadSchema>;
+
+interface ReportReadOutput {
+    success: boolean;
+    slug?: string;
+    content?: string;
+    message?: string;
+}
+
+/**
+ * Core implementation of report reading functionality
+ * Reads exclusively from local file storage
+ */
+async function executeReportRead(
+    input: ReportReadInput,
+    context: ToolExecutionContext
+): Promise<ReportReadOutput> {
+    const { identifier } = input;
+
+    logger.info("📖 Reading report from local storage", {
+        identifier,
+        agent: context.agent.name,
+    });
+
+    const localStore = getLocalReportStore();
+
+    // Clean the identifier - extract slug if it's an naddr or has nostr: prefix
+    let slug = identifier;
+
+    // Remove nostr: prefix if present
+    if (slug.startsWith("nostr:")) {
+        slug = slug.slice(6);
+    }
+
+    // If it looks like an naddr, decode it to extract the slug (d-tag)
+    // Reports are NDKArticle events (kind 30023)
+    if (slug.startsWith("naddr1")) {
+        try {
+            const decoded = nip19.decode(slug);
+            if (decoded.type === "naddr") {
+                // Verify this is a report (kind 30023) - NDKArticle
+                if (decoded.data.kind !== 30023) {
+                    return {
+                        success: false,
+                        message: `Invalid naddr kind ${decoded.data.kind} - report_read only accepts kind 30023 (NDKArticle) naddrs. Got: ${identifier}`,
+                    };
+                }
+                if (decoded.data.identifier) {
+                    slug = decoded.data.identifier;
+                    logger.debug("📖 Decoded naddr to slug", {
+                        originalIdentifier: identifier,
+                        extractedSlug: slug,
+                        kind: decoded.data.kind,
+                        agent: context.agent.name,
+                    });
+                } else {
+                    return {
+                        success: false,
+                        message: `Invalid naddr format - missing identifier (d-tag) in: ${identifier}`,
+                    };
+                }
+            } else {
+                return {
+                    success: false,
+                    message: `Invalid naddr format - could not extract report slug from: ${identifier}`,
+                };
+            }
+        } catch (decodeError) {
+            logger.warn("📖 Failed to decode naddr identifier", {
+                identifier,
+                error: decodeError instanceof Error ? decodeError.message : String(decodeError),
+                agent: context.agent.name,
+            });
+            return {
+                success: false,
+                message: `Failed to decode naddr identifier: ${identifier}. Please provide a valid slug or naddr.`,
+            };
+        }
+    }
+
+    // Validate the slug for path safety
+    try {
+        localStore.validateSlug(slug);
+    } catch (error) {
+        if (error instanceof InvalidSlugError) {
+            return {
+                success: false,
+                message: error.message,
+            };
+        }
+        throw error;
+    }
+
+    // Read from local storage
+    const content = await localStore.readReport(slug);
+
+    if (!content) {
+        logger.info("📭 No local report found", {
+            slug,
+            path: localStore.getReportPath(slug),
+            agent: context.agent.name,
+        });
+
+        return {
+            success: false,
+            message: `No report found with slug: ${slug}. The report may not have been written yet or synced from Nostr.`,
+        };
+    }
+
+    logger.info("✅ Report read successfully from local storage", {
+        slug,
+        contentLength: content.length,
+        agent: context.agent.name,
+    });
+
+    return {
+        success: true,
+        slug,
+        content,
+    };
+}
+
+/**
+ * Create an AI SDK tool for reading reports
+ */
+export function createReportReadTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description: "Read a report by slug identifier",
+
+        inputSchema: reportReadSchema,
+
+        execute: async (input: ReportReadInput) => {
+            return await executeReportRead(input, context);
+        },
+    });
+
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: ({ identifier }: ReportReadInput) => {
+            return `Reading report: ${identifier}`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/report_write.ts

@@ -0,0 +1,278 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { PendingDelegationsRegistry } from "@/services/ral";
+import { ReportService, getLocalReportStore, InvalidSlugError } from "@/services/reports";
+import { getReportEmbeddingService } from "@/services/reports/ReportEmbeddingService";
+import { getProjectContext } from "@/services/projects";
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+
+const reportWriteSchema = z.object({
+    slug: z.string().describe("The slug identifier for the article, used as the d-tag"),
+    title: z.string().describe("The title of the report"),
+    summary: z.string().describe("A one-line summary of the report"),
+    content: z.string().describe("The full content of the report in markdown format"),
+    hashtags: z
+        .array(z.string())
+        .default([])
+        .describe("Array of hashtags to add to the article (without the # prefix)"),
+    memorize: z
+        .boolean()
+        .default(false)
+        .describe(
+            "When true, the report content will be automatically added to this agent's system prompt as persistent context. Use this for reports that are fundamental to your role (e.g., architecture decisions, domain knowledge, project conventions) that you want to always have available."
+        ),
+    memorize_team: z
+        .boolean()
+        .default(false)
+        .describe(
+            "⚠️ HIGH CONTEXT COST - When true, the report content will be injected into the system prompt of ALL agents in the project, not just the authoring agent. Use ONLY for SHORT documents that are critical for EVERY agent to know. Examples: critical project-wide conventions, emergency procedures, or announcements that affect all agents. NEVER use for long documents or agent-specific information."
+        ),
+});
+
+type ReportWriteInput = z.infer<typeof reportWriteSchema>;
+type ReportWriteOutput = {
+    success: boolean;
+    articleId: string;
+    slug: string;
+    message: string;
+    /** Addressable event references for a-tagging on the tool use event */
+    referencedAddressableEvents: string[];
+    /** Warning messages for non-fatal issues (e.g., local write failed but Nostr succeeded) */
+    warnings?: string[];
+};
+
+/**
+ * Format report content for local storage with metadata header
+ */
+function formatReportContent(data: {
+    title: string;
+    summary: string;
+    content: string;
+    hashtags?: string[];
+}): string {
+    const lines: string[] = [];
+
+    // Add title
+    lines.push(`# ${data.title}`);
+    lines.push("");
+
+    // Add summary
+    if (data.summary) {
+        lines.push(`> ${data.summary}`);
+        lines.push("");
+    }
+
+    // Add hashtags if present
+    if (data.hashtags && data.hashtags.length > 0) {
+        lines.push(`**Tags:** ${data.hashtags.map((t) => `#${t}`).join(" ")}`);
+        lines.push("");
+    }
+
+    lines.push("---");
+    lines.push("");
+
+    // Add content
+    lines.push(data.content);
+
+    return lines.join("\n");
+}
+
+// Core implementation - extracted from existing execute function
+async function executeReportWrite(
+    input: ReportWriteInput,
+    context: ToolExecutionContext
+): Promise<ReportWriteOutput> {
+    const { slug, title, summary, content, hashtags, memorize, memorize_team } = input;
+
+    logger.info("📝 Writing report", {
+        slug,
+        title,
+        memorize,
+        memorize_team,
+        agent: context.agent.name,
+    });
+
+    const reportService = new ReportService();
+    const localStore = getLocalReportStore();
+
+    // Step 1: Validate slug BEFORE publishing to Nostr
+    // This prevents orphaned Nostr reports that can't be read back locally
+    try {
+        localStore.validateSlug(slug);
+    } catch (error) {
+        if (error instanceof InvalidSlugError) {
+            throw new Error(
+                `Invalid report slug "${slug}": ${error.message}. ` +
+                    "Slugs can only contain alphanumeric characters, hyphens, and underscores.",
+                { cause: error }
+            );
+        }
+        throw error;
+    }
+
+    // Step 2: Publish to Nostr
+    const result = await reportService.writeReport(
+        {
+            slug,
+            title,
+            summary,
+            content,
+            hashtags,
+            memorize,
+            memorizeTeam: memorize_team,
+        },
+        context.agent
+    );
+
+    // Step 3: Save to local storage
+    // Format the content for local storage
+    const formattedContent = formatReportContent({ title, summary, content, hashtags });
+
+    // The created_at is now (since we just published)
+    const createdAt = Math.floor(Date.now() / 1000);
+
+    // Try to save locally, but don't fail if Nostr publish succeeded
+    let localWriteFailed = false;
+    let localWriteError: string | undefined;
+    try {
+        await localStore.writeReport(slug, formattedContent, {
+            addressableRef: result.addressableRef,
+            createdAt,
+            slug,
+        });
+
+        logger.info("📁 Report saved to local storage", {
+            slug,
+            path: localStore.getReportPath(slug),
+        });
+    } catch (localError) {
+        // Nostr publish succeeded but local save failed - log warning but don't throw
+        localWriteFailed = true;
+        localWriteError = localError instanceof Error ? localError.message : String(localError);
+        logger.warn("⚠️ Report published to Nostr but local save failed", {
+            slug,
+            error: localWriteError,
+            nostrId: result.encodedId,
+        });
+        // Continue - the report is live on Nostr and will be hydrated later
+    }
+
+    // Step 4: Index in RAG for semantic search
+    try {
+        const projectCtx = getProjectContext();
+        const projectTagId = projectCtx.project.tagId();
+        const reportEmbeddingService = getReportEmbeddingService();
+
+        const publishedAt = Math.floor(Date.now() / 1000);
+        await reportEmbeddingService.indexReport(
+            { slug, title, summary, content, hashtags, publishedAt },
+            projectTagId,
+            context.agent.pubkey,
+            context.agent.name
+        );
+    } catch (ragError) {
+        // Don't fail the tool if RAG indexing fails
+        const ragMessage = ragError instanceof Error ? ragError.message : String(ragError);
+        logger.warn("Failed to index report in RAG", { slug, error: ragMessage });
+    }
+
+    let memorizeMessage = "";
+    if (memorize_team) {
+        memorizeMessage = " ⚠️ This report has been team-memorized and will be included in the system prompt of ALL agents in the project.";
+    } else if (memorize) {
+        memorizeMessage = " This report has been memorized and will be included in your system prompt.";
+    }
+
+    logger.info("✅ Report written successfully", {
+        slug,
+        articleId: result.encodedId,
+        addressableRef: result.addressableRef,
+        memorize,
+        memorize_team,
+        agent: context.agent.name,
+    });
+
+    // Register with PendingDelegationsRegistry for a-tag correlation
+    PendingDelegationsRegistry.registerAddressable(
+        context.agent.pubkey,
+        context.conversationId,
+        result.addressableRef
+    );
+
+    // Build warnings array if there were any non-fatal issues
+    const warnings: string[] = [];
+    if (localWriteFailed) {
+        warnings.push(
+            `Local write failed (${localWriteError}). Report is published to Nostr and will be hydrated from subscription.`
+        );
+    }
+
+    return {
+        success: true,
+        articleId: `nostr:${result.encodedId}`,
+        slug,
+        message: `Report "${title}" published successfully.${memorizeMessage}`,
+        // Include addressable reference for ToolExecutionTracker to add as a-tag
+        referencedAddressableEvents: [result.addressableRef],
+        // Include warnings if any non-fatal issues occurred
+        ...(warnings.length > 0 && { warnings }),
+    };
+}
+
+// AI SDK tool factory
+export function createReportWriteTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description: `Write reports and documentation as NDKArticle events. Use for creating persistent documentation ABOUT THE PROJECT, such as:
+- Architecture documentation
+- Implementation plans
+- Project summaries
+- Design decisions
+- Technical specifications
+- API documentation
+- Team guidelines and conventions
+
+Reports are stored on Nostr network and accessible via slug. Updates existing reports with same slug. Supports markdown format and hashtags for categorization. Reports can be read back with report_read or listed with reports_list.
+
+**CRITICAL:** Only use this for content ABOUT THE PROJECT. For content about your behavior or patterns in how you work, use lesson_learn instead.
+
+**NEVER use for:**
+- Behavioral patterns or workflows
+- User preferences or communication styles
+- Debugging approaches or work patterns
+- "I've learned to..." statements about your approach
+
+**Memorize Parameter**: Set memorize=true when the report contains information that is fundamental to your role and should always be available in your system prompt. Use this for:
+- Core architectural decisions you need to reference frequently
+- Domain knowledge essential to your function
+- Project conventions or patterns you must follow consistently
+- Any content you want persisted across all future conversations
+
+When memorize=true, a "memorize" tag is added to the article and the content will be automatically injected into your system prompt.
+
+**Memorize Team Parameter** (⚠️ USE WITH EXTREME CAUTION):
+Set memorize_team=true ONLY when the report MUST be visible to EVERY agent in the project.
+
+⚠️ **HIGH CONTEXT WINDOW COST** - This injects content into ALL agents' system prompts!
+
+**ONLY use memorize_team for:**
+- Critical project-wide conventions that ALL agents must follow
+- Emergency procedures or time-sensitive announcements
+- Extremely short (<500 chars) shared context that every agent needs
+
+**NEVER use memorize_team for:**
+- Long documents (architecture docs, specs, etc.)
+- Agent-specific information
+- Content that only some agents need
+- General documentation (use regular reports instead)
+
+When memorize_team=true, a "memorize_team" tag is added and the content will be injected into the system prompt of ALL agents.
+
+See also: lesson_learn (for behavioral insights)`,
+        inputSchema: reportWriteSchema,
+        execute: async (input: ReportWriteInput) => {
+            return await executeReportWrite(input, context);
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/reports_list.ts

@@ -0,0 +1,77 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { ReportService } from "@/services/reports";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+
+const reportsListSchema = z.object({});
+
+type ReportsListInput = z.infer<typeof reportsListSchema>;
+
+type ReportSummary = {
+    slug: string;
+    title?: string;
+    summary?: string;
+    author: string;
+    publishedAt?: number;
+    hashtags?: string[];
+};
+
+type ReportsListOutput = {
+    success: boolean;
+    reports: ReportSummary[];
+};
+
+// Core implementation - extracted from existing execute function
+async function executeReportsList(
+    _input: ReportsListInput,
+    context: ToolExecutionContext
+): Promise<ReportsListOutput> {
+    logger.info("📚 Listing reports", {
+        agent: context.agent.name,
+    });
+
+    const reportService = new ReportService();
+    const projectCtx = getProjectContext();
+
+    // Fetch all reports in the project
+    const rawReports = await reportService.listReports();
+
+    // Transform reports: remove id, convert author hex pubkey to slug
+    const reports: ReportSummary[] = rawReports.map((report) => {
+        // Try to resolve author pubkey to agent slug
+        const agent = projectCtx.getAgentByPubkey(report.author);
+        const authorSlug = agent?.slug ?? report.author;
+
+        return {
+            slug: report.slug,
+            title: report.title,
+            summary: report.summary,
+            author: authorSlug,
+            publishedAt: report.publishedAt,
+            hashtags: report.hashtags,
+        };
+    });
+
+    logger.info("✅ Reports listed successfully", {
+        total: reports.length,
+        agent: context.agent.name,
+    });
+
+    return {
+        success: true,
+        reports,
+    };
+}
+
+// AI SDK tool factory
+export function createReportsListTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description: "List NDKArticle reports from agents in the project",
+        inputSchema: reportsListSchema,
+        execute: async (input: ReportsListInput) => {
+            return await executeReportsList(input, context);
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/schedule_task.ts

@@ -0,0 +1,104 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { SchedulerService } from "@/services/scheduling";
+import type { AISdkTool } from "@/tools/types";
+import { resolveAgentSlug } from "@/services/agents";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import * as cron from "node-cron";
+import { z } from "zod";
+
+/**
+ * Creates a tool for scheduling tasks using cron notation
+ */
+export function createScheduleTaskTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description:
+            "Schedule a task using cron notation (e.g., '0 9 * * *' for daily at 9am, '*/5 * * * *' for every 5 minutes)",
+        inputSchema: z.object({
+            title: z
+                .string()
+                .optional()
+                .describe("A human-readable title for the scheduled task (e.g., 'Daily standup reminder')"),
+            prompt: z.string().describe("The prompt to execute when the task runs"),
+            schedule: z
+                .string()
+                .describe(
+                    "Cron expression for scheduling (e.g., '0 9 * * *' for daily at 9am, '0 * * * *' for hourly)"
+                ),
+            targetAgent: z
+                .string()
+                .nullable()
+                .describe(
+                    "Target agent slug (e.g., 'architect', 'claude-code'). Only agent slugs are accepted."
+                ),
+        }),
+        execute: async ({ title, prompt, schedule, targetAgent }) => {
+            // Validate cron expression - throw for invalid input (consistent with delegate tool)
+            if (!cron.validate(schedule)) {
+                throw new Error(
+                    `Invalid cron expression: ${schedule}. Examples: '0 9 * * *' (daily at 9am), '*/5 * * * *' (every 5 minutes), '0 0 * * 0' (weekly on Sunday)`
+                );
+            }
+
+            // Resolve target agent to pubkey if specified - throw for invalid slugs (consistent with delegate tool)
+            let toPubkey: string;
+            if (targetAgent) {
+                const resolution = resolveAgentSlug(targetAgent);
+                if (!resolution.pubkey) {
+                    const availableSlugsStr = resolution.availableSlugs.length > 0
+                        ? `Available agent slugs: ${resolution.availableSlugs.join(", ")}`
+                        : "No agents available in the current project context.";
+                    throw new Error(
+                        `Invalid agent slug: "${targetAgent}". Only agent slugs are accepted. ${availableSlugsStr}`
+                    );
+                }
+                toPubkey = resolution.pubkey;
+            } else {
+                // Default to self if no target specified
+                toPubkey = context.agent.pubkey;
+            }
+
+            const schedulerService = SchedulerService.getInstance();
+
+            // The agent scheduling the task is always the current agent
+            const fromPubkey = context.agent.pubkey;
+
+            // Add task to scheduler with both pubkeys and optional title
+            const taskId = await schedulerService.addTask(
+                schedule,
+                prompt,
+                fromPubkey,
+                toPubkey,
+                undefined, // projectId - let it be resolved from context
+                title
+            );
+
+            logger.info(
+                `Successfully created scheduled task ${taskId} with cron schedule: ${schedule}`
+            );
+
+            return {
+                success: true,
+                taskId,
+                message: `Task scheduled successfully with ID: ${taskId}`,
+                title,
+                schedule,
+                prompt,
+                targetAgent: targetAgent || "self",
+            };
+        },
+    });
+
+    // Attach getHumanReadableContent as non-enumerable property
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: (args: { title?: string; prompt: string; schedule: string; targetAgent?: string }) => {
+            const target = args.targetAgent ? ` for ${args.targetAgent}` : "";
+            const titlePart = args.title ? `'${args.title}' ` : "";
+            return `Scheduling task ${titlePart}with cron '${args.schedule}'${target}: ${args.prompt}`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/schedule_task_cancel.ts

@@ -0,0 +1,62 @@
+import { SchedulerService } from "@/services/scheduling";
+import type { ToolExecutionContext } from "@/tools/types";
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Creates a tool for canceling scheduled tasks
+ */
+export function createCancelScheduledTaskTool(_context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description: "Cancel a scheduled task (recurring or one-off) by its ID",
+        inputSchema: z.object({
+            taskId: z.string().describe("The ID of the task to cancel"),
+        }),
+        execute: async ({ taskId }) => {
+            try {
+                const schedulerService = SchedulerService.getInstance();
+
+                // Remove task from scheduler
+                const success = await schedulerService.removeTask(taskId);
+
+                if (!success) {
+                    return {
+                        success: false,
+                        error: `Task ${taskId} not found or could not be removed`,
+                        taskId,
+                    };
+                }
+
+                logger.info(`Successfully cancelled scheduled task ${taskId}`);
+
+                return {
+                    success: true,
+                    message: `Task ${taskId} cancelled successfully`,
+                    taskId,
+                };
+            } catch (error: unknown) {
+                logger.error(`Failed to cancel scheduled task ${taskId}:`, error);
+
+                return {
+                    success: false,
+                    error:
+                        error instanceof Error ? error.message : "Failed to cancel scheduled task",
+                    taskId,
+                };
+            }
+        },
+    });
+
+    // Attach getHumanReadableContent as non-enumerable property
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: (args: { taskId: string }) => {
+            return `Canceling scheduled task ${args.taskId}`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}