@tenex-chat/backend 0.9.1

package/src/prompts/fragments/02-agent-home-directory.ts

@@ -0,0 +1,114 @@
+import { readdirSync } from "node:fs";
+import type { AgentInstance } from "@/agents/types/runtime";
+import {
+    ensureAgentHomeDirectory,
+    getAgentHomeDirectory,
+    getAgentHomeInjectedFiles,
+} from "@/lib/agent-home";
+
+// Re-export for convenience (used by tests)
+export { getAgentHomeDirectory } from "@/lib/agent-home";
+import { logger } from "@/utils/logger";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Maximum number of entries to show in the home directory listing.
+ * Prevents prompt bloat if an agent has many files.
+ */
+const MAX_LISTING_ENTRIES = 50;
+
+/**
+ * Arguments for the agent home directory fragment.
+ */
+interface AgentHomeDirectoryArgs {
+    agent: AgentInstance;
+}
+
+/**
+ * Build the home directory listing with proper error handling.
+ * Creates the directory if it doesn't exist and returns a formatted listing.
+ */
+function buildHomeListing(homeDir: string, agentPubkey: string): string {
+    // Try to create the directory using the shared helper
+    if (!ensureAgentHomeDirectory(agentPubkey)) {
+        return "(home directory unavailable)";
+    }
+
+    // Try to list the directory contents
+    try {
+        const entries = readdirSync(homeDir, { withFileTypes: true }).sort((a, b) =>
+            a.name.localeCompare(b.name)
+        );
+
+        if (entries.length === 0) {
+            return "(empty)";
+        }
+
+        const totalCount = entries.length;
+        const displayEntries = entries.slice(0, MAX_LISTING_ENTRIES);
+        const lines = displayEntries.map((entry) => `  ${entry.name}${entry.isDirectory() ? "/" : ""}`);
+
+        if (totalCount > MAX_LISTING_ENTRIES) {
+            lines.push(`  ...and ${totalCount - MAX_LISTING_ENTRIES} more`);
+        }
+
+        return lines.join("\n");
+    } catch (error) {
+        logger.warn("Failed to list agent home dir:", error);
+        return "(unable to read directory)";
+    }
+}
+
+/**
+ * Agent home directory fragment.
+ * Provides agents with a personal workspace directory for notes, scripts, and other files.
+ * Also auto-injects contents of files starting with '+' into the prompt.
+ */
+export const agentHomeDirectoryFragment: PromptFragment<AgentHomeDirectoryArgs> = {
+    id: "agent-home-directory",
+    priority: 2, // Right after agent-identity (priority 1)
+    template: ({ agent }) => {
+        const homeDir = getAgentHomeDirectory(agent.pubkey);
+        const listing = buildHomeListing(homeDir, agent.pubkey);
+        const injectedFiles = getAgentHomeInjectedFiles(agent.pubkey);
+
+        const parts: string[] = [];
+
+        parts.push("## Your Home Directory\n");
+        parts.push(`You have a personal home directory at: \`${homeDir}\``);
+        parts.push("");
+        parts.push("**Current contents:**");
+        parts.push("```");
+        parts.push(listing);
+        parts.push("```");
+        parts.push("");
+        parts.push(
+            "Feel free to use this space for notes, helper scripts, temporary files, or any personal workspace needs. " +
+                "Use descriptive names for your files so you can easily find them later."
+        );
+        parts.push("");
+        parts.push(
+            "**Auto-injected files:** Files starting with `+` (e.g., `+NOTES.md`) are automatically injected into your system prompt. " +
+                "Use these for: critical reminders, preferences, or frequently-referenced notes."
+        );
+
+        // Inject +prefixed file contents
+        if (injectedFiles.length > 0) {
+            parts.push("");
+            parts.push("### Injected File Contents\n");
+
+            for (const file of injectedFiles) {
+                parts.push(`**${file.filename}:**`);
+                if (file.truncated) {
+                    parts.push("*(truncated to 1500 characters)*");
+                }
+                parts.push("```");
+                parts.push(file.content);
+                parts.push("```");
+                parts.push("");
+            }
+        }
+
+        return parts.join("\n");
+    },
+};

package/src/prompts/fragments/03-system-reminders-explanation.ts

@@ -0,0 +1,14 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Explains <system-reminder> tags that agents encounter in tool results and user messages.
+ * Always included — agents need this context before encountering any actual reminders.
+ */
+export const systemRemindersExplanationFragment: PromptFragment<Record<string, never>> = {
+    id: "system-reminders-explanation",
+    priority: 3,
+    template: () => {
+        return `## System Reminders
+Tool results and user messages may include \`<system-reminder>\` tags. These contain dynamic information from the system — behavioral guidance, context updates, and state notifications. They bear no direct relation to the specific tool results or user messages in which they appear. Follow the instructions within them.`;
+    },
+};

package/src/prompts/fragments/04-relay-configuration.ts

@@ -0,0 +1,38 @@
+import { getRelayUrls } from "@/nostr/relays";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Default relay URL used when no relays are configured.
+ * This mirrors the default in src/nostr/relays.ts
+ */
+const DEFAULT_RELAY_URL = "wss://tenex.chat";
+
+/**
+ * Relay configuration fragment.
+ * Provides agents with information about the configured Nostr relays.
+ * This helps agents understand where Nostr events are being published and received.
+ */
+export const relayConfigurationFragment: PromptFragment<Record<string, never>> = {
+    id: "relay-configuration",
+    priority: 4, // After global-system-prompt (3), before delegation-chain (5)
+    template: () => {
+        const relays = getRelayUrls();
+        const isDefault = relays.length === 1 && relays[0] === DEFAULT_RELAY_URL;
+
+        const parts: string[] = [];
+
+        parts.push("## Nostr Relay Configuration\n");
+
+        if (isDefault) {
+            parts.push("Using default relay:");
+        } else {
+            parts.push(`Connected to ${relays.length} relay${relays.length > 1 ? "s" : ""}:`);
+        }
+
+        for (const relay of relays) {
+            parts.push(`- ${relay}`);
+        }
+
+        return parts.join("\n");
+    },
+};

package/src/prompts/fragments/05-delegation-chain.ts

@@ -0,0 +1,45 @@
+/**
+ * Delegation Chain Fragment
+ *
+ * This fragment displays the delegation chain in the system prompt, showing
+ * agents their position in the multi-agent workflow hierarchy.
+ *
+ * Example output:
+ * ## Delegation Chain
+ * ```
+ * [User -> architect-orchestrator] [conversation 4f69d3302cf2]
+ *   -> [architect-orchestrator -> execution-coordinator] [conversation 8a2bc1e45678]
+ *     -> [execution-coordinator -> claude-code (you)] [conversation 1234567890ab]
+ * ```
+ */
+
+import type { DelegationChainEntry } from "@/conversations/types";
+import type { PromptFragment } from "../core/types";
+import { formatDelegationChain } from "@/utils/delegation-chain";
+
+interface DelegationChainArgs {
+    /** The delegation chain entries (each with full conversation ID stored) */
+    delegationChain: DelegationChainEntry[];
+    /** The pubkey of the current agent (to mark with "(you)") */
+    currentAgentPubkey: string;
+}
+
+export const delegationChainFragment: PromptFragment<DelegationChainArgs> = {
+    id: "delegation-chain",
+    priority: 5, // After identity (1) but before most other context
+    template: ({ delegationChain, currentAgentPubkey }) => {
+        if (!delegationChain || delegationChain.length === 0) {
+            return "";
+        }
+
+        const chainString = formatDelegationChain(delegationChain, currentAgentPubkey);
+
+        return `## Delegation Chain
+\`\`\`
+${chainString}
+\`\`\`
+
+This shows who initiated this request and how it reached you. The "(you)" marker indicates your position.
+`;
+    },
+};

package/src/prompts/fragments/06-agent-todos.ts

@@ -0,0 +1,74 @@
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import type { TodoItem } from "@/services/ral/types";
+import type { PromptFragment } from "../core/types";
+
+interface AgentTodosArgs {
+    conversation: ConversationStore;
+    agentPubkey: string;
+}
+
+function formatTodoItem(item: TodoItem): string {
+    const statusMarker: Record<string, string> = {
+        pending: "[ ]",
+        in_progress: "[~]",
+        done: "[x]",
+        skipped: "[-]",
+    };
+
+    let line = `${statusMarker[item.status]} ${item.title} (id: ${item.id})`;
+
+    if (item.status === "skipped" && item.skipReason) {
+        line += ` (skipped: ${item.skipReason})`;
+    }
+
+    return line;
+}
+
+export const agentTodosFragment: PromptFragment<AgentTodosArgs> = {
+    id: "agent-todos",
+    priority: 6, // After phases (5), before other context
+    template: ({ conversation, agentPubkey }) => {
+        const todos = conversation.getTodos(agentPubkey);
+
+        if (todos.length === 0) {
+            return "";
+        }
+
+        const parts: string[] = [];
+        const pending = todos.filter((t) => t.status === "pending");
+        const inProgress = todos.filter((t) => t.status === "in_progress");
+        const done = todos.filter((t) => t.status === "done");
+        const skipped = todos.filter((t) => t.status === "skipped");
+
+        parts.push("## Your Current Todo List");
+        parts.push("");
+
+        // Summary stats
+        parts.push(
+            `Status: ${pending.length} pending, ${inProgress.length} in progress, ${done.length} done, ${skipped.length} skipped`
+        );
+        parts.push("");
+
+        // List all items in order (array order is the source of truth)
+        for (const todo of todos) {
+            parts.push(formatTodoItem(todo));
+        }
+
+        parts.push("");
+        parts.push("**Instructions:**");
+        parts.push(
+            "- Use `todo_write` to mark items as 'in_progress' when starting, 'done' when complete"
+        );
+        parts.push("- If skipping an item, set status='skipped' and provide a skip_reason");
+        parts.push("- Items with 'pending' status have not been started and require attention");
+
+        if (pending.length > 0) {
+            parts.push("");
+            parts.push(
+                `**ATTENTION:** You have ${pending.length} pending todo item(s) that need to be addressed.`
+            );
+        }
+
+        return parts.join("\n");
+    },
+};

package/src/prompts/fragments/06-todo-usage-guidance.ts

@@ -0,0 +1,34 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Static guidance about when to use todo tools.
+ * This is shown to all agents that have todo_add in their tools array.
+ * Complements 06-agent-todos.ts which shows the actual todo list.
+ */
+export const todoUsageGuidanceFragment: PromptFragment = {
+    id: "todo-usage-guidance",
+    priority: 6, // Same priority as agent-todos, shown before the list
+    template: () => `## Task Tracking with Todos
+
+**IMPORTANT: Use \`todo_write()\` liberally and proactively!**
+
+Creating a todo list helps you stay organized, shows your progress to observers, and ensures nothing gets forgotten. It's always better to have a simple todo list than none at all.
+
+**Best Practice: Create todos EARLY in your work:**
+- As soon as you receive a task, create a todo list
+- Even 1-2 item lists are valuable for tracking progress
+- Update your todos as you work (mark in_progress, done, add new items)
+
+**Good candidates for todos:**
+- Any task you'll spend more than a few seconds on
+- Multi-step work (even just 2 steps)
+- Tasks that involve file changes, tool calls, or research
+- Work that others may want to observe or track
+
+**Task management rules:**
+- Only ONE task should be \`in_progress\` at a time
+- Mark tasks \`done\` immediately after completing (don't batch completions)
+- Use \`skipped\` with a reason if a task becomes irrelevant
+- Keep your todo list updated as work progresses
+`,
+};

package/src/prompts/fragments/07-meta-project-context.ts

@@ -0,0 +1,234 @@
+import type { AgentInstance } from "@/agents/types";
+import { agentStorage } from "@/agents/AgentStorage";
+import { conversationRegistry } from "@/conversations/ConversationRegistry";
+import { getDaemon } from "@/daemon";
+import { RALRegistry } from "@/services/ral/RALRegistry";
+import { getPubkeyService } from "@/services/PubkeyService";
+import { logger } from "@/utils/logger";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Meta-project context fragment - provides agents with awareness of
+ * their membership in OTHER projects and what's happening there.
+ *
+ * This enables cross-project awareness for agents that belong to multiple projects.
+ */
+
+interface MetaProjectContextArgs {
+    agent: AgentInstance;
+    currentProjectId?: string;
+}
+
+interface OtherProjectInfo {
+    projectId: string;  // Full project ID: "31933:pubkey:dTag"
+    dTag: string;       // Just the d-tag (human readable identifier)
+    title: string;
+    activeConversations: ActiveConversationSummary[];
+}
+
+interface ActiveConversationSummary {
+    title: string;
+    agentName: string;
+    status: string;      // "streaming", "running <tool>", "active"
+    duration: string;    // "5m", "1h 30m"
+}
+
+const MAX_OTHER_PROJECTS = 5;
+const MAX_CONVS_PER_PROJECT = 5;
+const MAX_SUMMARY_LENGTH = 150;
+const ELLIPSIS = "...";
+
+/**
+ * Sanitize text for safe inclusion in system prompt.
+ */
+function sanitizeForPrompt(text: string, maxLength: number = MAX_SUMMARY_LENGTH): string {
+    let sanitized = text
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+
+    if (sanitized.length > maxLength) {
+        sanitized = sanitized.substring(0, maxLength - ELLIPSIS.length) + ELLIPSIS;
+    }
+
+    return sanitized;
+}
+
+/**
+ * Format duration since a timestamp into a human-readable string.
+ */
+function formatDuration(startTimestampMs: number): string {
+    const now = Date.now();
+    const durationMs = now - startTimestampMs;
+    const seconds = Math.floor(durationMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+        const remainingMinutes = minutes % 60;
+        return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+
+/**
+ * Load other projects this agent belongs to and their active conversations.
+ */
+async function loadOtherProjectsContext(
+    agentPubkey: string,
+    currentProjectId?: string
+): Promise<OtherProjectInfo[]> {
+    try {
+        // Get all project dTags where this agent is a member
+        const agentProjectDTags = await agentStorage.getAgentProjects(agentPubkey);
+        
+        if (agentProjectDTags.length === 0) {
+            return [];
+        }
+
+        // Get daemon for known projects info
+        let daemon;
+        try {
+            daemon = getDaemon();
+        } catch {
+            // Daemon might not be available (e.g., in MCP-only mode or tests)
+            logger.debug("Meta-project context: daemon not available, skipping");
+            return [];
+        }
+
+        const knownProjects = daemon.getKnownProjects();
+        const ralRegistry = RALRegistry.getInstance();
+        const pubkeyService = getPubkeyService();
+
+        // Build map of dTag -> full project info
+        const dTagToProjectId = new Map<string, { projectId: string; title: string }>();
+        for (const [projectId, project] of knownProjects) {
+            // projectId format: "31933:pubkey:dTag"
+            const parts = projectId.split(":");
+            const dTag = parts[2];
+            if (dTag && agentProjectDTags.includes(dTag)) {
+                const title = project.tagValue("title") || dTag;
+                dTagToProjectId.set(dTag, { projectId, title });
+            }
+        }
+
+        // Filter out current project and limit
+        const otherProjectDTags = agentProjectDTags.filter(dTag => {
+            const info = dTagToProjectId.get(dTag);
+            return info && info.projectId !== currentProjectId;
+        });
+
+        const limitedDTags = otherProjectDTags.slice(0, MAX_OTHER_PROJECTS);
+        const results: OtherProjectInfo[] = [];
+
+        for (const dTag of limitedDTags) {
+            const projectInfo = dTagToProjectId.get(dTag);
+            if (!projectInfo) continue;
+
+            // Get active conversations for this project
+            const activeEntries = ralRegistry.getActiveEntriesForProject(projectInfo.projectId);
+            
+            // Deduplicate by conversation and take most interesting entry
+            const conversationMap = new Map<string, typeof activeEntries[0]>();
+            for (const entry of activeEntries) {
+                const existing = conversationMap.get(entry.conversationId);
+                if (!existing || 
+                    entry.isStreaming || 
+                    (entry.currentTool && !existing.isStreaming) ||
+                    entry.lastActivityAt > existing.lastActivityAt) {
+                    conversationMap.set(entry.conversationId, entry);
+                }
+            }
+
+            // Build conversation summaries
+            const activeConversations: ActiveConversationSummary[] = [];
+            let convCount = 0;
+
+            for (const [conversationId, entry] of conversationMap) {
+                if (convCount >= MAX_CONVS_PER_PROJECT) break;
+
+                // Get conversation title
+                let title = `Conversation ${conversationId.substring(0, 8)}...`;
+                const store = conversationRegistry.get(conversationId);
+                if (store) {
+                    const metadata = store.getMetadata();
+                    if (metadata.title) {
+                        title = sanitizeForPrompt(metadata.title, 60);
+                    }
+                }
+
+                // Get agent name
+                const agentName = pubkeyService.getNameSync(entry.agentPubkey);
+
+                // Build status
+                let status: string;
+                if (entry.isStreaming) {
+                    status = "streaming";
+                } else if (entry.currentTool) {
+                    status = `running ${entry.currentTool}`;
+                } else {
+                    status = "active";
+                }
+
+                const duration = formatDuration(entry.createdAt);
+
+                activeConversations.push({
+                    title,
+                    agentName,
+                    status,
+                    duration,
+                });
+
+                convCount++;
+            }
+
+            results.push({
+                projectId: projectInfo.projectId,
+                dTag,
+                title: projectInfo.title,
+                activeConversations,
+            });
+        }
+
+        return results;
+    } catch (error) {
+        logger.debug("Failed to load meta-project context", { error });
+        return [];
+    }
+}
+
+export const metaProjectContextFragment: PromptFragment<MetaProjectContextArgs> = {
+    id: "meta-project-context",
+    priority: 7, // Between delegation-chain (5) and active-conversations (8)
+    template: async ({ agent, currentProjectId }) => {
+        const otherProjects = await loadOtherProjectsContext(agent.pubkey, currentProjectId);
+
+        if (otherProjects.length === 0) {
+            return ""; // No other projects to show
+        }
+
+        const projectSections = otherProjects.map(project => {
+            const convLines = project.activeConversations.length > 0
+                ? project.activeConversations.map(conv => 
+                    `  - "${conv.title}" - ${conv.agentName} (${conv.status}, ${conv.duration})`
+                ).join("\n")
+                : "  - No active conversations";
+
+            return `### Project: ${project.title}
+- ID: ${project.dTag}
+- Active conversations:
+${convLines}`;
+        });
+
+        return `## Cross-Project Context
+
+You are also a member of these other projects:
+
+${projectSections.join("\n\n")}
+
+---`;
+    },
+};