@tenex-chat/backend 0.9.1

package/src/prompts/fragments/12-skills.ts

@@ -0,0 +1,127 @@
+import type { SkillData } from "@/services/skill";
+import type { PromptFragment } from "../core/types";
+
+interface SkillsArgs {
+    /** Legacy: concatenated skill content (for backward compatibility) */
+    skillContent?: string;
+    /** Individual skill data with title, content, and files */
+    skills?: SkillData[];
+}
+
+/**
+ * Escape XML attribute value to prevent injection
+ */
+function escapeAttrValue(value: string): string {
+    return value
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+
+/**
+ * Render a single skill with its title, content, and attached files.
+ * Title is escaped to prevent XML injection.
+ */
+function renderSkill(skill: SkillData): string {
+    const parts: string[] = [];
+
+    // Build attributes
+    const attrs: string[] = [];
+    if (skill.title) {
+        attrs.push(`title="${escapeAttrValue(skill.title)}"`);
+    }
+    if (skill.name) {
+        attrs.push(`name="${escapeAttrValue(skill.name)}"`);
+    }
+    attrs.push(`id="${skill.shortId}"`);
+
+    const attrStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+
+    parts.push(`<transient-skill${attrStr}>`);
+    parts.push(skill.content);
+
+    // List installed files if any
+    const successfulFiles = skill.installedFiles.filter((f) => f.success);
+    if (successfulFiles.length > 0) {
+        parts.push("");
+        parts.push("## Installed Files");
+        parts.push("The following files have been downloaded for this skill:");
+        for (const file of successfulFiles) {
+            parts.push(`- \`${file.absolutePath}\``);
+        }
+    }
+
+    // Note failed files if any
+    const failedFiles = skill.installedFiles.filter((f) => !f.success);
+    if (failedFiles.length > 0) {
+        parts.push("");
+        parts.push("## Failed File Downloads");
+        for (const file of failedFiles) {
+            parts.push(`- ${file.relativePath}: ${file.error}`);
+        }
+    }
+
+    parts.push("</transient-skill>");
+
+    return parts.join("\n");
+}
+
+/**
+ * Fragment for injecting skill content into the system prompt.
+ * Skills are kind:4202 events referenced via skill tags on the triggering event.
+ * Their content is fetched, files are downloaded, and everything is injected
+ * to provide transient capabilities/instructions.
+ *
+ * Unlike nudges, skills do NOT have tool permissions.
+ * Skills focus on providing context, instructions, and attached files.
+ */
+export const skillsFragment: PromptFragment<SkillsArgs> = {
+    id: "skills",
+    priority: 12, // After nudges (11), before available-agents (15)
+    template: ({ skillContent, skills }) => {
+        // New rendering path: individual skills with their data
+        if (skills && skills.length > 0) {
+            const header = `## Loaded Transient Skills
+
+The following skills have been loaded for this conversation. These provide additional context and capabilities:
+`;
+            const renderedSkills = skills.map((skill) => renderSkill(skill));
+            return header + renderedSkills.join("\n\n");
+        }
+
+        // Legacy fallback: just skillContent string
+        if (!skillContent || skillContent.trim().length === 0) {
+            return "";
+        }
+
+        return `<transient-skills>
+${skillContent}
+</transient-skills>`;
+    },
+    validateArgs: (args: unknown): args is SkillsArgs => {
+        if (typeof args !== "object" || args === null) return false;
+        const a = args as Record<string, unknown>;
+        // Optional: all fields are optional (empty skills is valid)
+        // When skills array is provided, validate each element has required shape
+        if (a.skills !== undefined) {
+            if (!Array.isArray(a.skills)) return false;
+            for (const skill of a.skills) {
+                if (typeof skill !== "object" || skill === null) return false;
+                const s = skill as Record<string, unknown>;
+                // content and shortId are required
+                if (typeof s.content !== "string") return false;
+                if (typeof s.shortId !== "string") return false;
+                // title and name are optional
+                if (s.title !== undefined && typeof s.title !== "string") return false;
+                if (s.name !== undefined && typeof s.name !== "string") return false;
+                // installedFiles must be an array
+                if (!Array.isArray(s.installedFiles)) return false;
+            }
+        }
+        // skillContent must be string if provided
+        if (a.skillContent !== undefined && typeof a.skillContent !== "string") return false;
+        return true;
+    },
+    expectedArgs: "{ skillContent?: string; skills?: SkillData[] }",
+};

package/src/prompts/fragments/13-available-nudges.ts

@@ -0,0 +1,122 @@
+import type { WhitelistItem } from "@/services/nudge";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Combined fragment for displaying available nudges AND skills to agents.
+ *
+ * Renders under a single "Available Nudges and Skills" heading so agents
+ * recognise this section when asked about either nudges or skills.
+ *
+ * - Shows subsection headers (### Nudges / ### Skills) when BOTH types are present.
+ * - Omits the subsection header when only one type exists.
+ * - Returns empty string when neither nudges nor skills are available.
+ */
+interface AvailableNudgesAndSkillsArgs {
+    /** Whitelisted nudges from the NudgeWhitelistService */
+    availableNudges?: WhitelistItem[];
+    /** Whitelisted skills from the NudgeSkillWhitelistService */
+    availableSkills?: WhitelistItem[];
+}
+
+/**
+ * Escape text for safe inclusion in prompt output.
+ * Prevents injection attacks by escaping special characters.
+ */
+function escapePromptText(value: string): string {
+    return value
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+
+/** Maximum description length for display in list items */
+const MAX_DESCRIPTION_LENGTH = 150;
+
+/**
+ * Format a single WhitelistItem into a markdown bullet line.
+ */
+function formatItem(item: WhitelistItem): string {
+    const name = item.name || item.eventId.substring(0, 12);
+    const description = item.description
+        ? item.description.replace(/\n/g, " ").substring(0, MAX_DESCRIPTION_LENGTH)
+        : "No description";
+    return `  - **${escapePromptText(name)}** (${item.eventId.substring(0, 12)}): ${escapePromptText(description)}`;
+}
+
+export const availableNudgesAndSkillsFragment: PromptFragment<AvailableNudgesAndSkillsArgs> = {
+    id: "available-nudges-and-skills",
+    priority: 13, // Before available-agents (15)
+    template: ({ availableNudges, availableSkills }) => {
+        const nudges = availableNudges ?? [];
+        const skills = availableSkills ?? [];
+        const hasNudges = nudges.length > 0;
+        const hasSkills = skills.length > 0;
+
+        if (!hasNudges && !hasSkills) {
+            return "";
+        }
+
+        const hasBoth = hasNudges && hasSkills;
+        const sections: string[] = [];
+
+        // --- Header ---
+        sections.push("## Available Nudges and Skills");
+        sections.push("");
+        sections.push(
+            "The following nudges and skills are available for use when delegating tasks. Pass their event IDs in the `nudges` parameter of the delegate tool to apply them to delegated agents."
+        );
+        sections.push("");
+        sections.push(
+            "Nudges can modify tool availability (only-tool, allow-tool, deny-tool) and inject additional context/instructions into the agent's system prompt."
+        );
+        sections.push(
+            "Skills provide transient capabilities and context without modifying tool availability."
+        );
+
+        // --- Nudges ---
+        if (hasNudges) {
+            sections.push("");
+            if (hasBoth) {
+                sections.push("### Nudges");
+                sections.push("");
+            }
+            sections.push(nudges.map(formatItem).join("\n"));
+        }
+
+        // --- Skills ---
+        if (hasSkills) {
+            sections.push("");
+            if (hasBoth) {
+                sections.push("### Skills");
+                sections.push("");
+            }
+            sections.push(skills.map(formatItem).join("\n"));
+        }
+
+        // --- Example ---
+        const exampleId =
+            (hasNudges ? nudges[0] : skills[0]).eventId.substring(0, 12);
+        sections.push("");
+        sections.push("Example usage:");
+        sections.push("```");
+        sections.push("delegate({");
+        sections.push("  delegations: [{");
+        sections.push('    recipient: "agent-slug",');
+        sections.push('    prompt: "Your task here",');
+        sections.push(`    nudges: ["${exampleId}..."]`);
+        sections.push("  }]");
+        sections.push("})");
+        sections.push("```");
+
+        return sections.join("\n");
+    },
+    validateArgs: (args: unknown): args is AvailableNudgesAndSkillsArgs => {
+        if (typeof args !== "object" || args === null) return false;
+        const a = args as Record<string, unknown>;
+        if (a.availableNudges !== undefined && !Array.isArray(a.availableNudges)) return false;
+        if (a.availableSkills !== undefined && !Array.isArray(a.availableSkills)) return false;
+        return true;
+    },
+    expectedArgs: "{ availableNudges?: WhitelistItem[], availableSkills?: WhitelistItem[] }",
+};

package/src/prompts/fragments/15-available-agents.ts

@@ -0,0 +1,53 @@
+import type { AgentInstance } from "@/agents/types";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Available agents fragment.
+ * Shows coworkers they can hand off to.
+ */
+interface AvailableAgentsArgs {
+    agents: AgentInstance[];
+    currentAgent: AgentInstance;
+    projectManagerPubkey?: string;
+}
+
+export const availableAgentsFragment: PromptFragment<AvailableAgentsArgs> = {
+    id: "available-agents",
+    priority: 15,
+    template: ({ agents, currentAgent, projectManagerPubkey }) => {
+        // Filter out current agent
+        const coworkers = agents.filter((agent) => agent.pubkey !== currentAgent.pubkey);
+
+        if (coworkers.length === 0) {
+            return "## Available Agents\nNo other agents are available.";
+        }
+
+        const agentList = coworkers
+            .map((agent) => {
+                // Check if this agent is the current PM of the project
+                const isPM = projectManagerPubkey && agent.pubkey === projectManagerPubkey;
+                const roleDisplay = isPM ? `${agent.role} [PM]` : agent.role;
+                const parts = [`(${agent.slug})`, `  Role: ${roleDisplay}`];
+
+                if (agent.useCriteria) {
+                    parts.push(`  Use Criteria: ${agent.useCriteria}`);
+                } else if (agent.description) {
+                    parts.push(`  Description: ${agent.description}`);
+                }
+
+                return parts.join("\n");
+            })
+            .join("\n\n");
+
+        return `## Available Agents
+You are part of a multi-agent system, these are agents immediately available in the system:
+
+${agentList}
+
+The PM of this project only has knowledge of *this* project.`;
+    },
+};
+
+// Register the fragment
+fragmentRegistry.register(availableAgentsFragment);

package/src/prompts/fragments/16-stay-in-your-lane.ts

@@ -0,0 +1,41 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Stay In Your Lane Fragment
+ *
+ * Educates agents about delegation boundaries and role respect.
+ * Encourages thoughtful delegation that respects both the delegator's
+ * and delegatee's roles, avoiding micromanagement.
+ */
+export const stayInYourLaneFragment: PromptFragment = {
+    id: "stay-in-your-lane",
+    priority: 16, // Right after available-agents (15)
+    template: () => `## Delegation Best Practices
+
+**Core Principle: Delegate WHAT needs to be done, not HOW to do it.**
+
+**Before delegating, ask yourself:**
+1. What is MY role and responsibility?
+2. What is the role of the agent I'm delegating to?
+3. Am I delegating the TASK or micromanaging the APPROACH?
+
+**Effective delegation:**
+- Provide necessary context and constraints
+- Trust the delegatee to use their expertise and tools
+- Focus on outcomes, not step-by-step instructions
+
+**Avoid:**
+- Telling other agents which specific tools to use
+- Prescribing implementation details outside your expertise
+- Duplicating work that the delegatee is better suited for
+- Micromanaging approaches when you should delegate the entire task
+
+**Example - BAD delegation:**
+"Follow this exact sequence: search the codebase for X, read files Y and Z, then modify function F with the following changes..."
+
+**Example - GOOD delegation:**
+"Find and fix the authentication bug in the login flow. The issue appears to be related to token validation."
+
+Each agent has specialized knowledge and tools - respect their expertise.
+`,
+};

package/src/prompts/fragments/17-todo-before-delegation.ts

@@ -0,0 +1,39 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Todo Before Delegation Fragment
+ *
+ * Instructs agents to establish a todo list before delegating complex tasks.
+ * This ensures agents have a clear workflow plan visible before spawning child work.
+ * Simple, single-step delegations are exempt from this requirement.
+ */
+export const todoBeforeDelegationFragment: PromptFragment = {
+    id: "todo-before-delegation",
+    priority: 17, // Right after stay-in-your-lane (16)
+    template: () => `## Todo List Before Delegation
+
+**Establish your todo list BEFORE delegating complex or multi-step tasks.**
+
+Before using any delegation tool for non-trivial work:
+
+1. **Create your todo list first** - Use \`todo_write()\` to outline your workflow plan
+2. **Include anticipated delegations** - Your todo list should reflect the work you plan to delegate
+3. **Mark your current task as in_progress** - Show what you're working on when delegating
+
+**When this applies:**
+- Multi-step tasks involving multiple delegations
+- Complex work requiring coordination across agents
+- Tasks where progress tracking matters
+
+**When you can skip this:**
+- Simple, single-step delegations (e.g., quick lookups, straightforward queries)
+- Follow-up messages to existing delegations
+
+**Why this matters:**
+- Your workflow plan becomes visible to observers and the system
+- It prevents orphaned delegations without context
+- It enables better coordination and status tracking across agents
+
+**Skipping the todo list for complex delegations may result in system warnings.**
+`,
+};

package/src/prompts/fragments/20-voice-mode.ts

@@ -0,0 +1,62 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+export interface VoiceModeOptions {
+    isVoiceMode: boolean;
+}
+
+const voiceModeFragment: PromptFragment<VoiceModeOptions> = {
+    id: "voice-mode",
+    priority: 20, // High priority to ensure voice instructions are prominent
+    template: (options: VoiceModeOptions) => {
+        if (!options.isVoiceMode) return "";
+
+        return `## Voice Mode Guidelines
+
+CRITICAL: You are currently in "voice mode" -- heed this guidelines consistently.
+
+You are generating text that will be converted to speech and read aloud. Please follow these guidelines:
+
+### Text Formatting for TTS
+- Use natural, conversational language that flows well when spoken
+- Avoid complex punctuation that doesn't translate well to speech
+- For larger numbers, use a mix (e.g., "15 thousand" instead of "15,000")
+- Avoid URLs, file paths, or code snippets unless absolutely necessary
+- If you must reference code, describe it in natural language
+
+### Response Structure
+- Keep sentences concise and clear
+- Use shorter paragraphs with natural pauses
+- Avoid bullet points or numbered lists - use flowing prose instead
+- Lead with the most important information
+- Use transitions like "First," "Next," "Additionally," for clarity
+
+### Tone and Delivery
+- Be warm and conversational, as if speaking directly to the user
+- Use active voice whenever possible
+- Include brief acknowledgments like "I understand" or "Let me help with that"
+- Avoid technical jargon unless necessary, and explain terms when used
+- Use natural fillers sparingly for a more human feel (e.g., "Well," "Now,")
+
+### Content Adaptation
+- Summarize lengthy content rather than reading it verbatim
+- Focus on key points and actionable information
+- When describing visual elements or code, use descriptive language
+- For errors or issues, explain them clearly without reading stack traces
+- Provide context before diving into details
+
+Remember: The user is listening, not reading. Make your response engaging and easy to follow by ear.`;
+    },
+};
+
+// Register the fragment
+fragmentRegistry.register(voiceModeFragment);
+
+/**
+ * Helper function to check if an event has voice mode enabled
+ */
+export function isVoiceMode(event: NDKEvent | undefined): boolean {
+    if (!event) return false;
+    return event.tagValue("mode") === "voice";
+}

package/src/prompts/fragments/22-scheduled-tasks.ts

@@ -0,0 +1,175 @@
+import type { AgentInstance } from "@/agents/types";
+import type { ScheduledTask } from "@/services/scheduling";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Converts a cron expression to a human-readable format
+ */
+function cronToHumanReadable(cronExpression: string): string {
+    const parts = cronExpression.split(" ");
+    if (parts.length !== 5) {
+        return cronExpression; // Return as-is if not a valid cron expression
+    }
+
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+
+    // Common patterns
+    if (
+        minute === "*" &&
+        hour === "*" &&
+        dayOfMonth === "*" &&
+        month === "*" &&
+        dayOfWeek === "*"
+    ) {
+        return "Every minute";
+    }
+
+    if (
+        minute.startsWith("*/") &&
+        hour === "*" &&
+        dayOfMonth === "*" &&
+        month === "*" &&
+        dayOfWeek === "*"
+    ) {
+        const interval = minute.replace("*/", "");
+        return `Every ${interval} minutes`;
+    }
+
+    if (hour.startsWith("*/") && dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+        const interval = hour.replace("*/", "");
+        return `Every ${interval} hours at minute ${minute}`;
+    }
+
+    if (hour === "*" && dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+        return `Every hour at minute ${minute}`;
+    }
+
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+        return `Daily at ${hour.padStart(2, "0")}:${minute.padStart(2, "0")} UTC`;
+    }
+
+    if (dayOfMonth === "*" && month === "*") {
+        const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+        const dayName = days[Number.parseInt(dayOfWeek, 10)] || dayOfWeek;
+        return `Every ${dayName} at ${hour.padStart(2, "0")}:${minute.padStart(2, "0")} UTC`;
+    }
+
+    if (month === "*") {
+        return `Monthly on day ${dayOfMonth} at ${hour.padStart(2, "0")}:${minute.padStart(2, "0")} UTC`;
+    }
+
+    // Fallback to the original expression
+    return cronExpression;
+}
+
+/**
+ * Format an ISO timestamp as a human-readable datetime
+ */
+function formatExecutionTime(isoTimestamp: string): string {
+    try {
+        const date = new Date(isoTimestamp);
+        return `${date.toLocaleString("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+            timeZone: "UTC",
+        })} UTC`;
+    } catch {
+        return isoTimestamp;
+    }
+}
+
+/**
+ * Formats scheduled tasks for display in the agent's system prompt
+ */
+function formatScheduledTasks(tasks: ScheduledTask[], agentPubkey: string): string {
+    // Filter tasks that belong to this agent (tasks where this agent is the target)
+    const myTasks = tasks.filter((task) => task.toPubkey === agentPubkey);
+
+    if (myTasks.length === 0) {
+        return "";
+    }
+
+    // Separate recurring and one-off tasks
+    const recurringTasks = myTasks.filter((task) => task.type !== "oneoff");
+    const oneoffTasks = myTasks.filter((task) => task.type === "oneoff");
+
+    const sections: string[] = [];
+
+    // Format recurring tasks
+    if (recurringTasks.length > 0) {
+        const recurringLines = recurringTasks.map((task, index) => {
+            const title = task.title || `Recurring Task ${index + 1}`;
+            const humanCron = cronToHumanReadable(task.schedule);
+            const lastRunInfo = task.lastRun
+                ? ` (last run: ${new Date(task.lastRun).toISOString()})`
+                : "";
+
+            return `- **${title}** [recurring]: ${humanCron} (cron: \`${task.schedule}\`)${lastRunInfo}
+  ID: \`${task.id}\`
+  Prompt: "${task.prompt.length > 100 ? `${task.prompt.substring(0, 100)}...` : task.prompt}"`;
+        });
+
+        sections.push(`### Recurring Tasks\n${recurringLines.join("\n\n")}`);
+    }
+
+    // Format one-off tasks
+    if (oneoffTasks.length > 0) {
+        const oneoffLines = oneoffTasks.map((task, index) => {
+            const title = task.title || `One-off Task ${index + 1}`;
+            const executeAtFormatted = task.executeAt
+                ? formatExecutionTime(task.executeAt)
+                : "Unknown";
+
+            return `- **${title}** [one-off]: Executes at ${executeAtFormatted}
+  ID: \`${task.id}\`
+  Prompt: "${task.prompt.length > 100 ? `${task.prompt.substring(0, 100)}...` : task.prompt}"`;
+        });
+
+        sections.push(`### One-off Tasks\n${oneoffLines.join("\n\n")}`);
+    }
+
+    const totalCount = myTasks.length;
+    const summary =
+        totalCount === 1
+            ? "1 scheduled task"
+            : `${totalCount} scheduled tasks (${recurringTasks.length} recurring, ${oneoffTasks.length} one-off)`;
+
+    return `## Your Scheduled Tasks
+
+You have ${summary} that will trigger automatically:
+
+${sections.join("\n\n")}
+
+Use \`schedule_tasks_list\` to see all tasks or \`schedule_task_cancel\` to remove any by ID.`;
+}
+
+// Scheduled tasks fragment - shows agent's scheduled tasks in system prompt
+interface ScheduledTasksArgs {
+    agent: AgentInstance;
+    scheduledTasks: ScheduledTask[];
+}
+
+export const scheduledTasksFragment: PromptFragment<ScheduledTasksArgs> = {
+    id: "scheduled-tasks",
+    priority: 22, // Between voice-mode (20) and retrieved-lessons (24)
+    template: ({ agent, scheduledTasks }) => {
+        return formatScheduledTasks(scheduledTasks, agent.pubkey);
+    },
+    validateArgs: (args): args is ScheduledTasksArgs => {
+        return (
+            args !== null &&
+            typeof args === "object" &&
+            "agent" in args &&
+            "scheduledTasks" in args &&
+            Array.isArray((args as ScheduledTasksArgs).scheduledTasks)
+        );
+    },
+    expectedArgs: "{ agent: AgentInstance, scheduledTasks: ScheduledTask[] }",
+};
+
+// Register the fragment
+fragmentRegistry.register(scheduledTasksFragment);

package/src/prompts/fragments/24-retrieved-lessons.ts

@@ -0,0 +1,26 @@
+import type { AgentInstance } from "@/agents/types";
+import type { NDKAgentLesson } from "@/events/NDKAgentLesson";
+import { formatLessonsWithReminder } from "@/utils/lessonFormatter";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+// Retrieved lessons fragment - formats lessons from ProjectContext
+interface RetrievedLessonsArgs {
+    agent: AgentInstance;
+    agentLessons: Map<string, NDKAgentLesson[]>;
+}
+
+export const retrievedLessonsFragment: PromptFragment<RetrievedLessonsArgs> = {
+    id: "retrieved-lessons",
+    priority: 24, // Before learn-tool-directive
+    template: ({ agent, agentLessons }) => {
+        // Get only this agent's lessons
+        const myLessons = agentLessons.get(agent.pubkey) || [];
+
+        // Use centralized formatter (handles empty case and adds reminder)
+        return formatLessonsWithReminder(myLessons);
+    },
+};
+
+// Register the fragment
+fragmentRegistry.register(retrievedLessonsFragment);