@tenex-chat/backend 0.9.1

package/src/services/event-context/EventContextService.ts

@@ -0,0 +1,108 @@
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import type { EventContext } from "@/nostr/types";
+import type { ToolExecutionContext } from "@/tools/types";
+
+export interface CreateEventContextOptions {
+    model?: string;
+    /** Incremental LLM runtime in milliseconds since last event was published */
+    llmRuntime?: number;
+}
+
+/**
+ * Resolve the correct recipient pubkey for a completion event from the delegation chain.
+ *
+ * This function looks up the conversation's delegation chain and returns the immediate
+ * delegator (second-to-last entry). This ensures completions route back up the delegation
+ * stack even when RAL state is lost (e.g., daemon restart) and the triggeringEvent
+ * is from a different source (e.g., user responding to an ask).
+ *
+ * Exception: when the chain origin's pubkey matches the triggering event's pubkey,
+ * the caller is interacting directly (not via delegation). In this case the function
+ * returns undefined so the caller falls back to triggeringEvent.pubkey, avoiding
+ * mis-routing the completion to the intermediate delegator.
+ *
+ * The delegation chain is persisted in the ConversationStore, so it survives restarts.
+ *
+ * Architecture note: This function is in services/event-context/ (layer 3) because
+ * it imports ConversationStore. AgentEventEncoder (layer 2, in nostr/) cannot import
+ * ConversationStore directly - instead, it receives the pre-resolved pubkey via
+ * EventContext.completionRecipientPubkey.
+ *
+ * @param conversationStore - The conversation store (may be undefined in MCP context)
+ * @param triggeringEventPubkey - The pubkey of the event that triggered this RAL (optional)
+ * @returns The immediate delegator's pubkey, or undefined when:
+ *   - no delegation chain exists (or is too short)
+ *   - the triggering event pubkey matches the chain origin (direct-interaction case)
+ */
+export function resolveCompletionRecipient(
+    conversationStore: ConversationStore | undefined,
+    triggeringEventPubkey?: string
+): string | undefined {
+    if (!conversationStore) {
+        return undefined;
+    }
+
+    const delegationChain = conversationStore.metadata?.delegationChain;
+
+    if (delegationChain && delegationChain.length >= 2) {
+        // The delegation chain is ordered [origin, ..., delegator, current_agent]
+        // We want the second-to-last entry (the immediate delegator)
+        const immediateDelegator = delegationChain[delegationChain.length - 2];
+        const origin = delegationChain[0];
+
+        // If the chain origin directly triggered this RAL, the delegation is
+        // already complete. Route back to them directly (return undefined so
+        // the caller falls back to triggeringEvent.pubkey).
+        // In ask-resume, the original trigger is RESTORED to the delegator's
+        // message, so this condition is never true there.
+        if (triggeringEventPubkey && triggeringEventPubkey === origin.pubkey) {
+            return undefined;
+        }
+
+        return immediateDelegator.pubkey;
+    }
+
+    // No delegation chain or chain too short - caller should fall back to triggeringEvent.pubkey
+    return undefined;
+}
+
+/**
+ * Create EventContext for publishing events.
+ * Handles missing conversation context gracefully (e.g., in MCP context).
+ *
+ * For completion events, this function pre-resolves the completion recipient pubkey
+ * from the delegation chain stored in ConversationStore. This ensures completions
+ * route back to the immediate delegator even when:
+ * - RAL state is lost (e.g., daemon restart)
+ * - The triggeringEvent is from a different source (e.g., user responding to an ask)
+ *
+ * When the chain origin directly triggers the RAL (direct-interaction case), the
+ * resolved recipient is undefined and the completion routes to the triggering event's
+ * pubkey instead (see resolveCompletionRecipient for details).
+ */
+export function createEventContext(
+    context: ToolExecutionContext,
+    options?: CreateEventContextOptions | string
+): EventContext {
+    // Support legacy call signature: createEventContext(context, model)
+    const opts: CreateEventContextOptions = typeof options === "string"
+        ? { model: options }
+        : options ?? {};
+
+    const conversation = context.getConversation?.();
+    const rootEventId = conversation?.getRootEventId() ?? context.triggeringEvent?.id;
+
+    // Resolve completion recipient from delegation chain (layer-3 operation)
+    // This pre-resolves the pubkey so AgentEventEncoder (layer 2) doesn't need to import ConversationStore
+    const completionRecipientPubkey = resolveCompletionRecipient(conversation, context.triggeringEvent?.pubkey);
+
+    return {
+        triggeringEvent: context.triggeringEvent,
+        rootEvent: rootEventId ? { id: rootEventId } : {},
+        conversationId: context.conversationId,
+        model: opts.model ?? context.agent.llmConfig,
+        ralNumber: context.ralNumber,
+        llmRuntime: opts.llmRuntime,
+        completionRecipientPubkey,
+    };
+}

package/src/services/event-context/index.ts

@@ -0,0 +1,2 @@
+export { createEventContext, resolveCompletionRecipient } from "./EventContextService";
+export type { CreateEventContextOptions } from "./EventContextService";

package/src/services/heuristics/ContextBuilder.ts

@@ -0,0 +1,106 @@
+/**
+ * Context Builder for Heuristics
+ *
+ * Builds O(1) precomputed context from RAL state and conversation data.
+ * CRITICAL: All operations must be O(1) - no expensive scans allowed.
+ */
+
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import type { RALRegistry } from "@/services/ral/RALRegistry";
+import type { HeuristicContext } from "./types";
+
+/**
+ * Configuration for context builder
+ */
+export interface ContextBuilderConfig {
+  /** Maximum recent tools to include in context (default: 10) */
+  maxRecentTools?: number;
+}
+
+/**
+ * Build heuristic context from current RAL state.
+ * All data is precomputed for O(1) access.
+ * BLOCKER 1 FIX: Uses O(1) precomputed summary from RALRegistry.
+ */
+export function buildHeuristicContext(params: {
+  agentPubkey: string;
+  conversationId: string;
+  ralNumber: number;
+  toolName: string;
+  toolCallId: string;
+  toolArgs: unknown;
+  toolResult: unknown;
+  ralRegistry: RALRegistry;
+  conversationStore: ConversationStore;
+  currentBranch?: string;
+  config?: ContextBuilderConfig;
+}): HeuristicContext {
+  const {
+    agentPubkey,
+    conversationId,
+    ralNumber,
+    toolName,
+    toolCallId,
+    toolArgs,
+    toolResult,
+    ralRegistry,
+    conversationStore,
+    currentBranch,
+  } = params;
+
+  // Get O(1) precomputed summary from RAL (BLOCKER 1 FIX)
+  const summary = ralRegistry.getHeuristicSummary(agentPubkey, conversationId, ralNumber) ?? {
+    recentTools: [],
+    flags: {
+      hasTodoWrite: false,
+      hasDelegation: false,
+      hasVerification: false,
+      hasGitAgentCommit: false,
+    },
+    pendingDelegationCount: 0,
+  };
+
+  // Build state from O(1) precomputed summary
+  const state = {
+    hasTodoWrite: summary.flags.hasTodoWrite,
+    hasDelegation: summary.flags.hasDelegation,
+
+    // O(1) counter from summary (no expensive scan)
+    pendingDelegationCount: summary.pendingDelegationCount,
+
+    // Current branch
+    currentBranch,
+
+    // Check if on worktree branch (heuristic: contains .worktrees or feature/)
+    isWorktreeBranch: currentBranch
+      ? currentBranch.includes("feature/") || currentBranch.includes(".worktrees")
+      : false,
+
+    // Check if verification was performed (tests, builds)
+    hasVerification: summary.flags.hasVerification,
+
+    // Check if git-agent was used (via delegation)
+    hasGitAgentCommit: summary.flags.hasGitAgentCommit,
+
+    // Total message count (O(1) - stored in ConversationStore)
+    messageCount: conversationStore.getMessageCount(),
+  };
+
+  // BLOCKER 3 FIX: Generate timestamp here, not in heuristics (for purity)
+  const evaluationTimestamp = Date.now();
+
+  return {
+    agentPubkey,
+    conversationId,
+    ralNumber,
+    evaluationTimestamp,
+    tool: {
+      name: toolName,
+      callId: toolCallId,
+      args: toolArgs,
+      result: toolResult,
+    },
+    state,
+    recentTools: summary.recentTools, // O(1) - bounded array from summary
+  };
+}

package/src/services/heuristics/HeuristicEngine.ts

@@ -0,0 +1,200 @@
+/**
+ * HeuristicEngine - Core orchestration for reactive heuristic system
+ *
+ * Evaluates heuristics post-tool execution and manages violation state.
+ * CRITICAL: Hard error boundaries ensure single heuristic failure cannot crash pipeline.
+ */
+
+import { logger } from "@/utils/logger";
+import { formatViolations } from "./formatters";
+import type {
+  Heuristic,
+  HeuristicContext,
+  HeuristicEngineConfig,
+  HeuristicViolation,
+} from "./types";
+
+/**
+ * HeuristicEngine orchestrates heuristic evaluation with strict error boundaries.
+ *
+ * Key guarantees:
+ * - Single heuristic failure CANNOT crash tool pipeline
+ * - All heuristics get O(1) precomputed context
+ * - Violations are stored in RALRegistry namespace
+ * - Max 3 warnings per LLM step
+ */
+export class HeuristicEngine {
+  private heuristics: Map<string, Heuristic> = new Map();
+  private config: Required<HeuristicEngineConfig>;
+
+  constructor(config: HeuristicEngineConfig = {}) {
+    this.config = {
+      maxWarningsPerStep: config.maxWarningsPerStep ?? 3,
+      debug: config.debug ?? false,
+    };
+
+    if (this.config.debug) {
+      logger.info("[HeuristicEngine] Initialized", {
+        maxWarningsPerStep: this.config.maxWarningsPerStep,
+      });
+    }
+  }
+
+  /**
+   * Register a heuristic for evaluation
+   */
+  register(heuristic: Heuristic): void {
+    if (this.heuristics.has(heuristic.id)) {
+      logger.warn("[HeuristicEngine] Duplicate heuristic ID - replacing", {
+        id: heuristic.id,
+      });
+    }
+
+    this.heuristics.set(heuristic.id, heuristic);
+
+    if (this.config.debug) {
+      logger.info("[HeuristicEngine] Registered heuristic", {
+        id: heuristic.id,
+        name: heuristic.name,
+      });
+    }
+  }
+
+  /**
+   * Unregister a heuristic
+   */
+  unregister(heuristicId: string): void {
+    this.heuristics.delete(heuristicId);
+  }
+
+  /**
+   * Get all registered heuristics
+   */
+  getAll(): Heuristic[] {
+    return Array.from(this.heuristics.values());
+  }
+
+  /**
+   * Evaluate all heuristics against the current context.
+   * Each heuristic is wrapped in a hard try/catch boundary.
+   *
+   * @param context - Precomputed O(1) context
+   * @returns Array of violations (empty if all rules pass)
+   */
+  evaluate(context: HeuristicContext): HeuristicViolation[] {
+    const violations: HeuristicViolation[] = [];
+
+    for (const heuristic of this.heuristics.values()) {
+      const violation = this.evaluateSingle(heuristic, context);
+      if (violation) {
+        violations.push(violation);
+      }
+    }
+
+    return violations;
+  }
+
+
+  /**
+   * Evaluate a single heuristic with error boundary.
+   * CRITICAL: This method MUST NOT throw - it catches all errors.
+   */
+  private evaluateSingle(heuristic: Heuristic, context: HeuristicContext): HeuristicViolation | null {
+    try {
+      const violation = heuristic.evaluate(context);
+
+      if (violation && this.config.debug) {
+        logger.info("[HeuristicEngine] Violation detected", {
+          heuristicId: heuristic.id,
+          violationId: violation.id,
+          severity: violation.severity,
+          title: violation.title,
+        });
+      }
+
+      return violation;
+    } catch (error) {
+      // HARD ERROR BOUNDARY: Log but never throw
+      logger.error("[HeuristicEngine] Heuristic evaluation failed - skipping", {
+        heuristicId: heuristic.id,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+
+      return null;
+    }
+  }
+
+
+  /**
+   * Format violations for LLM injection.
+   * Sorts by severity (errors first) and limits to maxWarningsPerStep.
+   *
+   * @param violations - All detected violations
+   * @returns Markdown string for system message
+   */
+  formatForInjection(violations: HeuristicViolation[]): string {
+    if (violations.length === 0) {
+      return "";
+    }
+
+    // Sort: errors first, then by timestamp (most recent first)
+    const sorted = violations.sort((a, b) => {
+      if (a.severity !== b.severity) {
+        return a.severity === "error" ? -1 : 1;
+      }
+      return b.timestamp - a.timestamp;
+    });
+
+    // Limit to max warnings
+    const limited = sorted.slice(0, this.config.maxWarningsPerStep);
+
+    if (this.config.debug && limited.length < sorted.length) {
+      logger.info("[HeuristicEngine] Truncated violations for injection", {
+        total: sorted.length,
+        shown: limited.length,
+        hidden: sorted.length - limited.length,
+      });
+    }
+
+    return formatViolations(limited);
+  }
+
+  /**
+   * Get debug summary of current state
+   */
+  getDebugInfo(): {
+    registeredCount: number;
+    heuristics: Array<{ id: string; name: string }>;
+    config: Required<HeuristicEngineConfig>;
+  } {
+    return {
+      registeredCount: this.heuristics.size,
+      heuristics: Array.from(this.heuristics.values()).map((h) => ({
+        id: h.id,
+        name: h.name,
+      })),
+      config: this.config,
+    };
+  }
+}
+
+/** Global singleton instance */
+let engineInstance: HeuristicEngine | null = null;
+
+/**
+ * Get or create the global HeuristicEngine instance
+ */
+export function getHeuristicEngine(config?: HeuristicEngineConfig): HeuristicEngine {
+  if (!engineInstance) {
+    engineInstance = new HeuristicEngine(config);
+  }
+  return engineInstance;
+}
+
+/**
+ * Reset the global instance (for testing)
+ */
+export function resetHeuristicEngine(): void {
+  engineInstance = null;
+}

package/src/services/heuristics/formatters.ts

@@ -0,0 +1,58 @@
+/**
+ * Formatters for heuristic violations
+ *
+ * Converts violations into markdown warnings for LLM context.
+ * Output is wrapped in <system-reminder> tags for consistent injection.
+ */
+
+import { wrapInSystemReminder } from "@/services/system-reminder";
+import type { HeuristicViolation } from "./types";
+
+/**
+ * Format a single violation as a markdown warning block
+ */
+export function formatViolation(violation: HeuristicViolation): string {
+  const icon = violation.severity === "error" ? "🚨" : "⚠️";
+  const severityLabel = violation.severity.toUpperCase();
+
+  return [
+    `${icon} **${severityLabel}: ${violation.title}**`,
+    "",
+    violation.message,
+  ].join("\n");
+}
+
+/**
+ * Format multiple violations into a single system reminder block.
+ * Output is wrapped in <system-reminder> tags for consistent injection
+ * and appending to user messages.
+ *
+ * @param violations - List of violations to format (max 3 recommended)
+ * @returns Content wrapped in system-reminder tags, ready for injection
+ */
+export function formatViolations(violations: HeuristicViolation[]): string {
+  if (violations.length === 0) {
+    return "";
+  }
+
+  const formattedViolations = violations.map(formatViolation).join("\n\n---\n\n");
+
+  const content = [
+    "# Heuristic Reminders",
+    "",
+    "The following pattern violations were detected based on your recent actions:",
+    "",
+    formattedViolations,
+    "",
+    "Please address these before continuing.",
+  ].join("\n");
+
+  return wrapInSystemReminder(content);
+}
+
+/**
+ * Format a violation for debug logging (single line)
+ */
+export function formatViolationForLog(violation: HeuristicViolation): string {
+  return `[${violation.severity}] ${violation.heuristicId}: ${violation.title}`;
+}

package/src/services/heuristics/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Heuristics System - Reactive Agent Guidance
+ *
+ * Provides real-time guidance to agents based on their actions.
+ * Heuristics are pure, synchronous functions that check rules
+ * and generate warnings when patterns are violated.
+ */
+
+export { HeuristicEngine, getHeuristicEngine, resetHeuristicEngine } from "./HeuristicEngine";
+export { formatViolation, formatViolations, formatViolationForLog } from "./formatters";
+export * from "./types";
+export * from "./rules";

package/src/services/heuristics/rules/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Heuristic Rules Registry
+ *
+ * Exports all available heuristics for registration with the engine.
+ */
+
+export { todoReminderOnToolUseHeuristic } from "./todoReminderOnToolUse";
+
+// Note: todoBeforeDelegationHeuristic is deprecated - delegation now has hard enforcement
+// at the tool level (delegate.ts, delegate_crossproject.ts) which blocks before heuristics run.
+// Keeping the export for backward compatibility but not registering it.
+export { todoBeforeDelegationHeuristic } from "./todoBeforeDelegation";
+
+import type { Heuristic } from "../types";
+import { todoReminderOnToolUseHeuristic } from "./todoReminderOnToolUse";
+
+/**
+ * Get all default heuristics
+ */
+export function getDefaultHeuristics(): Heuristic[] {
+  return [
+    // todoBeforeDelegationHeuristic removed - delegation is now hard-blocked at tool level
+    todoReminderOnToolUseHeuristic,
+  ];
+}

package/src/services/heuristics/rules/todoBeforeDelegation.ts

@@ -0,0 +1,69 @@
+/**
+ * TodoWrite Before Delegation Heuristic
+ *
+ * Ensures agents create a TODO list before delegating complex tasks.
+ * This helps track progress and provides clear task breakdown.
+ */
+
+import type { Heuristic, HeuristicContext, HeuristicResult } from "../types";
+
+const HEURISTIC_ID = "todo-before-delegation";
+
+/**
+ * Tools that trigger delegation
+ */
+const DELEGATION_TOOLS = new Set([
+  "mcp__tenex__delegate",
+  "mcp__tenex__delegate_crossproject",
+]);
+
+/**
+ * Check if TodoWrite was called before delegation in this RAL
+ */
+export const todoBeforeDelegationHeuristic: Heuristic = {
+  id: HEURISTIC_ID,
+  name: "TodoWrite Before Delegation",
+  description: "Agents should create a TODO list before delegating complex tasks",
+
+  evaluate(context: HeuristicContext): HeuristicResult {
+    // Only check if this is a delegation tool
+    if (!DELEGATION_TOOLS.has(context.tool.name)) {
+      return null;
+    }
+
+    // Check if TodoWrite was called in this RAL
+    if (context.state.hasTodoWrite) {
+      return null; // Rule satisfied
+    }
+
+    // Check recent tool history for TodoWrite
+    const hasTodoInRecent = context.recentTools.some(
+      (tool) => tool.name === "TodoWrite"
+    );
+
+    if (hasTodoInRecent) {
+      return null; // Rule satisfied
+    }
+
+    // Violation: Delegation without TODO
+    // BLOCKER 3 FIX: Use deterministic ID from context timestamp, not Date.now()
+    return {
+      id: `${HEURISTIC_ID}-${context.tool.callId}-${context.ralNumber}`,
+      heuristicId: HEURISTIC_ID,
+      title: "Missing TODO List Before Delegation",
+      severity: "warning",
+      timestamp: context.evaluationTimestamp,
+      message: [
+        "You are delegating a task without creating a TODO list first.",
+        "",
+        "**Why this matters:**",
+        "- TODO lists help track progress across multiple delegations",
+        "- They provide clear task breakdown for complex work",
+        "- They ensure nothing is forgotten after delegation completes",
+        "",
+        "**Recommended action:**",
+        "Use the `TodoWrite` tool to create a task list before delegating, unless this is a simple, single-step delegation.",
+      ].join("\n"),
+    };
+  },
+};

package/src/services/heuristics/rules/todoReminderOnToolUse.ts

@@ -0,0 +1,63 @@
+/**
+ * Todo Reminder on Tool Use Heuristic
+ *
+ * Injects a system reminder on ANY tool use (except todo_write variants)
+ * when the agent has no todos. This encourages proactive todo list creation.
+ */
+
+import type { Heuristic, HeuristicContext, HeuristicResult } from "../types";
+
+const HEURISTIC_ID = "todo-reminder-on-tool-use";
+
+/**
+ * Tools that are exempt from the todo reminder
+ * These are the todo tools themselves (both naked and MCP-wrapped)
+ */
+const TODO_TOOLS = new Set([
+  "todo_write",
+  "mcp__tenex__todo_write",
+  "TodoWrite", // Legacy name that might appear in recentTools
+]);
+
+/**
+ * Inject a reminder to use todo_write on every non-todo tool call
+ * when the agent has no todos.
+ */
+export const todoReminderOnToolUseHeuristic: Heuristic = {
+  id: HEURISTIC_ID,
+  name: "Todo Reminder on Tool Use",
+  description: "Reminds agents to create a todo list when using tools without one",
+
+  evaluate(context: HeuristicContext): HeuristicResult {
+    // Skip if this IS a todo tool
+    if (TODO_TOOLS.has(context.tool.name)) {
+      return null;
+    }
+
+    // Skip if agent already has todos (hasTodoWrite flag means they've called todo_write this RAL)
+    if (context.state.hasTodoWrite) {
+      return null;
+    }
+
+    // Violation: Using a tool without having created todos
+    // Note: The framework already injects heuristic violations as system messages,
+    // so no need to wrap in <system-reminder> tags here
+    return {
+      id: `${HEURISTIC_ID}-${context.tool.callId}`,
+      heuristicId: HEURISTIC_ID,
+      title: "Consider Creating a Todo List",
+      severity: "warning",
+      timestamp: context.evaluationTimestamp,
+      message: [
+        "You haven't created a todo list yet. Consider using `todo_write()` to track your work.",
+        "",
+        "Benefits of using todos:",
+        "- Shows your progress to observers",
+        "- Helps you stay organized",
+        "- Required before delegating to other agents",
+        "",
+        "Even a simple 1-2 item todo list is valuable!",
+      ].join("\n"),
+    };
+  },
+};