@tenex-chat/backend 0.9.1

package/src/nostr/relays.ts

@@ -0,0 +1,43 @@
+import { config } from "@/services/ConfigService";
+
+/**
+ * Default Nostr relay URLs for TENEX
+ */
+const DEFAULT_RELAY_URLS = ["wss://tenex.chat"];
+
+/**
+ * Validate WebSocket URL format
+ * @param url - URL to validate
+ * @returns true if URL is valid WebSocket URL
+ */
+function isValidWebSocketUrl(url: string): boolean {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "ws:" || parsed.protocol === "wss:";
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get relay URLs for NDK connection
+ * Priority: config file > defaults
+ * @returns Array of validated WebSocket relay URLs
+ */
+export function getRelayUrls(): string[] {
+    // Check config file
+    try {
+        const tenexConfig = config.getConfig();
+        if (tenexConfig.relays && tenexConfig.relays.length > 0) {
+            const urls = tenexConfig.relays.filter((url) => isValidWebSocketUrl(url));
+            if (urls.length > 0) {
+                return urls;
+            }
+        }
+    } catch {
+        // Config not loaded yet, fall through to defaults
+    }
+
+    // Fall back to defaults
+    return DEFAULT_RELAY_URLS;
+}

package/src/nostr/trace-context.ts

@@ -0,0 +1,39 @@
+import { propagation, context as otelContext, trace } from "@opentelemetry/api";
+import { getLLMSpanId } from "../telemetry/LLMSpanRegistry.js";
+
+/**
+ * Event-like object that has a tags array.
+ * Compatible with NDKEvent and plain objects.
+ */
+export interface EventWithTags {
+    tags: string[][];
+}
+
+/**
+ * Inject W3C trace context into an event's tags.
+ * This allows the daemon to link incoming events back to their parent span.
+ * Also adds trace_context_llm which links to the LLM execution span for better debugging.
+ *
+ * @param event - Any object with a tags array (NDKEvent or plain object)
+ */
+export function injectTraceContext(event: EventWithTags): void {
+    const carrier: Record<string, string> = {};
+    propagation.inject(otelContext.active(), carrier);
+    if (carrier.traceparent) {
+        event.tags.push(["trace_context", carrier.traceparent]);
+    }
+
+    // Add trace context that links to LLM execution span (more useful for debugging)
+    const activeSpan = trace.getActiveSpan();
+    if (activeSpan) {
+        const spanContext = activeSpan.spanContext();
+        const traceId = spanContext.traceId;
+
+        // Use LLM span ID if available (links to actual LLM execution)
+        // Otherwise fall back to current span ID
+        const llmSpanId = getLLMSpanId(traceId);
+        const spanIdToUse = llmSpanId || spanContext.spanId;
+
+        event.tags.push(["trace_context_llm", `00-${traceId}-${spanIdToUse}-01`]);
+    }
+}

package/src/nostr/types.ts

@@ -0,0 +1,227 @@
+/**
+ * Type definitions for agent Nostr events.
+ * Centralized types for event encoding and publishing.
+ */
+
+import type { LanguageModelUsageWithCostUsd } from "@/llm/types";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+// ============================================================================
+// Intent Types - Express what agents want to communicate
+// ============================================================================
+
+export interface CompletionIntent {
+    content: string;
+    usage?: LanguageModelUsageWithCostUsd;
+    summary?: string;
+    // Note: llmRuntime is now tracked via EventContext.llmRuntime for all events
+}
+
+export interface ConversationIntent {
+    content: string;
+    isReasoning?: boolean;
+    usage?: LanguageModelUsageWithCostUsd;
+}
+
+export interface DelegationIntent {
+    delegations: Array<{
+        recipient: string;
+        request: string;
+        branch?: string;
+    }>;
+    type?: "delegation" | "delegation_followup" | "ask";
+}
+
+/**
+ * A single-select question where user picks one option (or provides their own answer).
+ */
+export interface SingleSelectQuestion {
+    type: "question";
+    /** Short title for the question (displayed as header) */
+    title: string;
+    /** Full question text */
+    question: string;
+    /** Optional suggestions - if omitted, question is fully open-ended */
+    suggestions?: string[];
+}
+
+/**
+ * A multi-select question where user can pick multiple options (or provide their own answer).
+ */
+export interface MultiSelectQuestion {
+    type: "multiselect";
+    /** Short title for the question (displayed as header) */
+    title: string;
+    /** Full question text */
+    question: string;
+    /** Optional options - if omitted, question is fully open-ended */
+    options?: string[];
+}
+
+/**
+ * Union type for all question types.
+ */
+export type AskQuestion = SingleSelectQuestion | MultiSelectQuestion;
+
+export interface AskIntent {
+    title: string;
+    context: string;
+    questions: AskQuestion[];
+}
+
+export interface ErrorIntent {
+    message: string;
+    errorType?: string;
+}
+
+export interface LessonIntent {
+    title: string;
+    lesson: string;
+    detailed?: string;
+    category?: string;
+    hashtags?: string[];
+}
+
+export interface ScheduledTaskInfo {
+    id: string;
+    title: string;
+    schedule: string; // Cron expression or ISO timestamp
+    /** Agent slug when resolvable, otherwise a truncated pubkey prefix */
+    targetAgent: string;
+    type: "cron" | "oneoff";
+    lastRun?: number; // Unix timestamp in seconds
+}
+
+export interface StatusIntent {
+    type: "status";
+    agents: Array<{ pubkey: string; slug: string }>;
+    models: Array<{ slug: string; agents: string[] }>;
+    tools: Array<{ name: string; agents: string[] }>;
+    worktrees?: string[]; // Array of branch names, first is default
+    scheduledTasks?: ScheduledTaskInfo[];
+}
+
+export interface ToolUseIntent {
+    toolName: string;
+    content: string; // e.g., "Reading $path"
+    args?: unknown; // Tool arguments to be serialized
+    referencedEventIds?: string[]; // Event IDs to reference with q-tags (e.g., delegation event IDs)
+    referencedAddressableEvents?: string[]; // Addressable event references with a-tags (e.g., "30023:pubkey:d-tag")
+    usage?: LanguageModelUsageWithCostUsd; // Cumulative usage from previous steps
+}
+
+/**
+ * Intent for intervention review requests.
+ * Used when the InterventionService detects that a user hasn't responded
+ * to an agent's completion and triggers a human-replica review.
+ *
+ * Names are pre-resolved by the caller (InterventionPublisher) to avoid
+ * layer violations - AgentEventEncoder (layer 2) cannot import PubkeyService (layer 3).
+ */
+export interface InterventionReviewIntent {
+    /** Pubkey of the intervention agent (human-replica) to notify */
+    targetPubkey: string;
+    /** The conversation ID being reviewed */
+    conversationId: string;
+    /** Human-readable name of the user who hasn't responded (pre-resolved) */
+    userName: string;
+    /** Human-readable name of the agent that completed work (pre-resolved) */
+    agentName: string;
+}
+
+/**
+ * Intent for delegation marker events.
+ * Delegation markers track the lifecycle of delegation conversations.
+ * They are created when a delegation is initiated and updated when it completes/aborts.
+ */
+export interface DelegationMarkerIntent {
+    /** The delegation conversation ID (the child conversation) */
+    delegationConversationId: string;
+    /** The agent pubkey that received the delegation */
+    recipientPubkey: string;
+    /** The parent conversation ID (where the delegator is working) */
+    parentConversationId: string;
+    /** Delegation status: pending, completed, or aborted */
+    status: "pending" | "completed" | "aborted";
+    /** When the delegation was initiated (Unix timestamp in seconds) */
+    initiatedAt?: number;
+    /** When the delegation completed (Unix timestamp in seconds) - only for completed/aborted */
+    completedAt?: number;
+    /** If aborted, the reason for the abort */
+    abortReason?: string;
+}
+
+export type AgentIntent =
+    | CompletionIntent
+    | ConversationIntent
+    | DelegationIntent
+    | AskIntent
+    | ErrorIntent
+    | LessonIntent
+    | StatusIntent
+    | ToolUseIntent
+    | InterventionReviewIntent
+    | DelegationMarkerIntent;
+
+// ============================================================================
+// Event Context - Execution context provided by RAL
+// ============================================================================
+
+export interface EventContext {
+    triggeringEvent: NDKEvent; // The event that triggered this execution (for reply threading)
+    rootEvent: { id?: string }; // The conversation root event (only ID is used for tagging)
+    conversationId: string; // Required for conversation lookup
+    executionTime?: number;
+    model?: string;
+    cost?: number; // LLM cost in USD
+    ralNumber: number; // RAL number for this execution - required for all conversational events
+    /** Incremental LLM runtime in milliseconds since last event was published */
+    llmRuntime?: number;
+    /** Total accumulated LLM runtime for this RAL (used in completion events) */
+    llmRuntimeTotal?: number;
+    /**
+     * Pre-resolved recipient pubkey for completion events.
+     * When set, the encoder uses this pubkey for the completion p-tag instead of
+     * triggeringEvent.pubkey. This supports delegation chain routing where completions
+     * must route back to the immediate delegator, not the event that happened to
+     * trigger the current execution (e.g., a user responding to an ask).
+     *
+     * Resolved by createEventContext() (layer 3, in services/event-context/) from the
+     * ConversationStore's delegation chain. This avoids layer violations - neither
+     * AgentPublisher nor AgentEventEncoder (layer 2) can import ConversationStore (layer 3).
+     */
+    completionRecipientPubkey?: string;
+}
+
+// ============================================================================
+// Publisher Config Types
+// ============================================================================
+
+/**
+ * Configuration for delegation events.
+ */
+export interface DelegateConfig {
+    /** The pubkey of the agent to delegate to */
+    recipient: string;
+    /** The content/instructions for the delegation */
+    content: string;
+    /** Optional branch for worktree support */
+    branch?: string;
+    /** Optional nudge event IDs to apply to the delegated agent */
+    nudges?: string[];
+}
+
+/**
+ * Configuration for ask events.
+ * Uses the multi-question format (title + questions).
+ */
+export interface AskConfig {
+    /** The pubkey of the recipient (usually project owner/human) */
+    recipient: string;
+    /** Full context explaining why these questions are being asked */
+    context: string;
+    /** Overall title encompassing all questions */
+    title: string;
+    /** Array of questions (single-select or multi-select) */
+    questions: AskQuestion[];
+}

package/src/nostr/utils.ts

@@ -0,0 +1,84 @@
+import { getProjectContext } from "@/services/projects";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Check if an event is from an agent (either project agent or individual agent)
+ * @param event - The NDK event to check
+ * @returns true if the event is from an agent, false if from a user
+ */
+export function isEventFromAgent(event: NDKEvent): boolean {
+    const projectCtx = getProjectContext();
+
+    // Check if it's from the project manager
+    if (projectCtx.projectManager?.pubkey === event.pubkey) {
+        return true;
+    }
+
+    // Check if it's from any of the registered agents
+    for (const agent of projectCtx.agents.values()) {
+        if (agent.pubkey === event.pubkey) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if an event is from a user (not from an agent)
+ * @param event - The NDK event to check
+ * @returns true if the event is from a user, false if from an agent
+ */
+export function isEventFromUser(event: NDKEvent): boolean {
+    return !isEventFromAgent(event);
+}
+
+/**
+ * Get the agent slug if the event is from an agent
+ * @param event - The NDK event to check
+ * @returns The agent slug if found, undefined otherwise
+ */
+export function getAgentSlugFromEvent(event: NDKEvent): string | undefined {
+    if (!event.pubkey) return undefined;
+
+    const projectCtx = getProjectContext();
+    for (const [slug, agent] of projectCtx.agents) {
+        if (agent.pubkey === event.pubkey) {
+            return slug;
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * Get the agent pubkeys that are targeted by this event based on p-tags
+ * @param event - The NDK event to check
+ * @returns Array of agent pubkeys that are targeted by this event
+ */
+export function getTargetedAgentPubkeys(event: NDKEvent): string[] {
+    const projectCtx = getProjectContext();
+    const targetedPubkeys: string[] = [];
+
+    // Get all p-tags from the event
+    const pTags = event.getMatchingTags("p");
+    if (pTags.length === 0) {
+        return [];
+    }
+
+    // Check each p-tag to see if it matches an agent
+    for (const pTag of pTags) {
+        const pubkey = pTag[1];
+        if (!pubkey) continue;
+
+        // Check if this pubkey belongs to an agent
+        for (const agent of projectCtx.agents.values()) {
+            if (agent.pubkey === pubkey) {
+                targetedPubkeys.push(pubkey);
+                break;
+            }
+        }
+    }
+
+    return targetedPubkeys;
+}

package/src/prompts/core/FragmentRegistry.ts

@@ -0,0 +1,30 @@
+import type { PromptFragment } from "./types";
+
+export class FragmentRegistry {
+    private fragments = new Map<string, PromptFragment<unknown>>();
+
+    register<T>(fragment: PromptFragment<T>): void {
+        if (!fragment.id) {
+            throw new Error("Fragment must have an id");
+        }
+        this.fragments.set(fragment.id, fragment as PromptFragment<unknown>);
+    }
+
+    get(id: string): PromptFragment<unknown> | undefined {
+        return this.fragments.get(id);
+    }
+
+    has(id: string): boolean {
+        return this.fragments.has(id);
+    }
+
+    clear(): void {
+        this.fragments.clear();
+    }
+
+    getAllIds(): string[] {
+        return Array.from(this.fragments.keys());
+    }
+}
+
+export const fragmentRegistry = new FragmentRegistry();

package/src/prompts/core/PromptBuilder.ts

@@ -0,0 +1,98 @@
+import { formatAnyError } from "@/lib/error-formatter";
+import { fragmentRegistry } from "./FragmentRegistry";
+import type { FragmentConfig, PromptFragment } from "./types";
+
+export class PromptBuilder {
+    private fragments: FragmentConfig[] = [];
+
+    add<T>(fragmentId: string, args: T, condition?: (args: T) => boolean): this {
+        if (!fragmentRegistry.has(fragmentId)) {
+            throw new Error(
+                `Fragment "${fragmentId}" not found in registry. Available fragments: ${fragmentRegistry.getAllIds().join(", ")}`
+            );
+        }
+        this.fragments.push({
+            fragmentId,
+            args,
+            condition: condition ? (unknownArgs) => condition(unknownArgs as T) : undefined,
+        });
+        return this;
+    }
+
+    addFragment<T>(fragment: PromptFragment<T>, args: T, condition?: (args: T) => boolean): this {
+        fragmentRegistry.register(fragment);
+        this.fragments.push({
+            fragmentId: fragment.id,
+            args,
+            condition: condition ? (unknownArgs) => condition(unknownArgs as T) : undefined,
+        });
+        return this;
+    }
+
+    async build(): Promise<string> {
+        const fragmentsWithPriority = await Promise.all(
+            this.fragments
+                .filter((config) => !config.condition || config.condition(config.args))
+                .map(async (config) => {
+                    const fragment = fragmentRegistry.get(config.fragmentId);
+                    if (!fragment) {
+                        throw new Error(`Fragment ${config.fragmentId} not found`);
+                    }
+
+                    // Validate arguments if validator is provided
+                    if (fragment.validateArgs && !fragment.validateArgs(config.args)) {
+                        const receivedArgs = JSON.stringify(config.args, null, 2);
+                        const expectedDesc =
+                            fragment.expectedArgs || "Check fragment definition for expected arguments";
+                        throw new Error(
+                            `Fragment "${config.fragmentId}" received invalid arguments.\n` +
+                                `Expected: ${expectedDesc}\n` +
+                                `Received: ${receivedArgs}`
+                        );
+                    }
+
+                    try {
+                        return {
+                            priority: fragment.priority || 50,
+                            content: await fragment.template(config.args),
+                        };
+                    } catch (error) {
+                        const errorMessage = formatAnyError(error);
+                        const receivedArgs = JSON.stringify(config.args, null, 2);
+                        throw new Error(
+                            `Error executing fragment "${config.fragmentId}":\n` +
+                                `${errorMessage}\n` +
+                                `Arguments provided: ${receivedArgs}\n` +
+                                `Expected: ${fragment.expectedArgs || "Check fragment definition"}`,
+                            { cause: error }
+                        );
+                    }
+                })
+        );
+
+        return fragmentsWithPriority
+            .sort((a, b) => a.priority - b.priority)
+            .map((f) => f.content)
+            .filter((content) => content.trim().length > 0)
+            .join("\n\n");
+    }
+
+    clear(): this {
+        this.fragments = [];
+        return this;
+    }
+
+    getFragmentCount(): number {
+        return this.fragments.length;
+    }
+
+    /**
+     * Static method for building a single fragment without creating an instance
+     * @param fragmentId The ID of the fragment to build
+     * @param args The arguments to pass to the fragment
+     * @returns The built fragment content as a string
+     */
+    static async buildFragment<T>(fragmentId: string, args: T): Promise<string> {
+        return await new PromptBuilder().add(fragmentId, args).build();
+    }
+}

package/src/prompts/core/index.ts

@@ -0,0 +1,3 @@
+export { FragmentRegistry, fragmentRegistry } from "./FragmentRegistry";
+export { PromptBuilder } from "./PromptBuilder";
+export type { FragmentConfig, PromptFragment } from "./types";

package/src/prompts/core/types.ts

@@ -0,0 +1,13 @@
+export interface PromptFragment<T = unknown> {
+    id: string;
+    priority?: number;
+    template: (args: T) => string | Promise<string>;
+    validateArgs?: (args: unknown) => args is T;
+    expectedArgs?: string; // Description of expected arguments for error messages
+}
+
+export interface FragmentConfig {
+    fragmentId: string;
+    args: unknown;
+    condition?: (args: unknown) => boolean;
+}

package/src/prompts/fragments/00-global-system-prompt.ts

@@ -0,0 +1,44 @@
+import { config } from "@/services/ConfigService";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Global system prompt fragment.
+ *
+ * This fragment allows users to configure a system prompt that is added to ALL
+ * projects. It is loaded from the global config ($TENEX_BASE_DIR/config.json).
+ *
+ * Users can configure this via: `tenex setup global-system-prompt`
+ *
+ * Priority 3 places it after the core identity fragments (priorities 1 and 2),
+ * so it is ordered like other fragments instead of being prepended.
+ */
+
+// Empty args - the fragment loads content from config
+type GlobalSystemPromptArgs = Record<string, never>;
+
+export const globalSystemPromptFragment: PromptFragment<GlobalSystemPromptArgs> = {
+    id: "global-system-prompt",
+    priority: 3,
+    template: () => {
+        try {
+            const tenexConfig = config.getConfig();
+            const globalPrompt = tenexConfig.globalSystemPrompt;
+
+            // Check if enabled and has content
+            if (!globalPrompt?.content || globalPrompt.content.trim().length === 0) {
+                return "";
+            }
+
+            // Check if explicitly disabled
+            if (globalPrompt.enabled === false) {
+                return "";
+            }
+
+            // Return the user-configured global system prompt
+            return globalPrompt.content.trim();
+        } catch {
+            // Config not loaded yet or error - return empty string
+            return "";
+        }
+    },
+};

package/src/prompts/fragments/01-agent-identity.ts

@@ -0,0 +1,69 @@
+import type { AgentInstance } from "@/agents/types";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Identity fragment for agents.
+ */
+interface AgentIdentityArgs {
+    agent: AgentInstance;
+    projectTitle: string;
+    projectOwnerPubkey: string;
+    /**
+     * Actual worktree path where code execution happens.
+     * This is displayed as "Absolute Path" in the system prompt.
+     */
+    workingDirectory?: string;
+    /**
+     * Current conversation ID (full hex).
+     * First 12 characters are displayed as short ID in the system prompt.
+     */
+    conversationId?: string;
+}
+
+export const agentIdentityFragment: PromptFragment<AgentIdentityArgs> = {
+    id: "agent-identity",
+    priority: 1,
+    template: ({ agent, projectTitle, projectOwnerPubkey, workingDirectory, conversationId }) => {
+        const parts: string[] = [];
+
+        // Identity
+        parts.push("# Your Identity\n");
+        parts.push(`Your name: ${agent.name} (${agent.slug})`);
+        if (agent.role) {
+            parts.push(`Your role: ${agent.role}`);
+        }
+        parts.push(`Your npub: ${agent.signer.npub}`);
+        parts.push(
+            `Your nsec: ${agent.signer.nsec} -- this is your real nsec and you CAN and SHOULD use it when you encounter a tool that needs an nsec.`
+        );
+        parts.push("");
+
+        // Instructions
+        if (agent.instructions) {
+            parts.push(`## Your Instructions\n${agent.instructions}\n`);
+        }
+
+        // Project context
+        const contextLines = [
+            "## Project Context",
+            `- Title: "${projectTitle}"`,
+            `- Today's Date: ${new Date().toISOString().split("T")[0]}`,
+        ];
+        if (workingDirectory) {
+            contextLines.push(`- Absolute Path: ${workingDirectory}`);
+        }
+        contextLines.push(`- User (Owner) pubkey: "${projectOwnerPubkey}"`);
+        if (conversationId) {
+            const shortId = shortenConversationId(conversationId);
+            contextLines.push(`- Current Conversation (short): ${shortId}`);
+        }
+        parts.push(contextLines.join("\n"));
+
+        return parts.join("\n");
+    },
+};
+
+// Register the fragment
+fragmentRegistry.register(agentIdentityFragment);