@tenex-chat/backend 0.9.1

package/src/agents/supervision/heuristics/HeuristicRegistry.ts

@@ -0,0 +1,114 @@
+import { logger } from "@/utils/logger";
+import type { Heuristic, HeuristicTiming, PostCompletionContext, PreToolContext } from "../types";
+
+/**
+ * Singleton registry for managing supervision heuristics
+ * Allows registration and retrieval of heuristics by timing and tool filter
+ */
+export class HeuristicRegistry {
+    private static instance: HeuristicRegistry | null = null;
+
+    private heuristics: Map<string, Heuristic<unknown>> = new Map();
+
+    private constructor() {
+        // Private constructor for singleton pattern
+    }
+
+    /**
+     * Get the singleton instance of the registry
+     */
+    static getInstance(): HeuristicRegistry {
+        if (!HeuristicRegistry.instance) {
+            HeuristicRegistry.instance = new HeuristicRegistry();
+        }
+        return HeuristicRegistry.instance;
+    }
+
+    /**
+     * Register a heuristic with the registry
+     * @param heuristic - The heuristic to register
+     */
+    register<T>(heuristic: Heuristic<T>): void {
+        if (this.heuristics.has(heuristic.id)) {
+            logger.warn(
+                `[HeuristicRegistry] Heuristic with id "${heuristic.id}" already registered, overwriting`
+            );
+        }
+        this.heuristics.set(heuristic.id, heuristic as Heuristic<unknown>);
+        logger.debug(`[HeuristicRegistry] Registered heuristic: ${heuristic.id} (${heuristic.timing})`);
+    }
+
+    /**
+     * Get all heuristics for a specific timing
+     * @param timing - The timing to filter by
+     * @returns Array of heuristics matching the timing
+     */
+    getByTiming(timing: HeuristicTiming): Heuristic<unknown>[] {
+        const result: Heuristic<unknown>[] = [];
+        for (const heuristic of this.heuristics.values()) {
+            if (heuristic.timing === timing) {
+                result.push(heuristic);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Get pre-tool-execution heuristics filtered by tool name
+     * Returns heuristics that either have no tool filter or include the given tool
+     * @param toolName - The tool name to filter by
+     * @returns Array of applicable pre-tool heuristics
+     */
+    getPreToolHeuristics(toolName: string): Heuristic<PreToolContext>[] {
+        const result: Heuristic<PreToolContext>[] = [];
+        for (const heuristic of this.heuristics.values()) {
+            if (heuristic.timing !== "pre-tool-execution") {
+                continue;
+            }
+            // Include if no tool filter or tool is in the filter list
+            if (!heuristic.toolFilter || heuristic.toolFilter.includes(toolName)) {
+                result.push(heuristic as Heuristic<PreToolContext>);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Get all post-completion heuristics
+     * @returns Array of post-completion heuristics
+     */
+    getPostCompletionHeuristics(): Heuristic<PostCompletionContext>[] {
+        return this.getByTiming("post-completion") as Heuristic<PostCompletionContext>[];
+    }
+
+    /**
+     * Get a specific heuristic by ID
+     * @param id - The heuristic ID
+     * @returns The heuristic or undefined if not found
+     */
+    get(id: string): Heuristic<unknown> | undefined {
+        return this.heuristics.get(id);
+    }
+
+    /**
+     * Clear all registered heuristics (mainly for testing)
+     */
+    clear(): void {
+        this.heuristics.clear();
+        logger.debug("[HeuristicRegistry] Cleared all heuristics");
+    }
+
+    /**
+     * Get all registered heuristic IDs (for debugging)
+     */
+    getAllIds(): string[] {
+        return Array.from(this.heuristics.keys());
+    }
+
+    /**
+     * Get the count of registered heuristics
+     */
+    get size(): number {
+        return this.heuristics.size;
+    }
+}

package/src/agents/supervision/heuristics/PendingTodosHeuristic.ts

@@ -0,0 +1,93 @@
+import type {
+    CorrectionAction,
+    Heuristic,
+    HeuristicDetection,
+    PostCompletionContext,
+    VerificationResult,
+} from "../types";
+
+/**
+ * Heuristic that prevents agents from completing when they have pending or in_progress todos.
+ *
+ * This ensures agents don't abandon work they've planned. If an agent creates a todo list
+ * but tries to finish without completing (or explicitly skipping) all items, this heuristic
+ * will block the completion and prompt the agent to address their remaining todos.
+ *
+ * Uses skipVerification=true because this is an objective check - either todos are incomplete
+ * or they aren't. No LLM judgment needed.
+ */
+export class PendingTodosHeuristic implements Heuristic<PostCompletionContext> {
+    id = "pending-todos";
+    name = "Agent Completing With Pending Todos";
+    timing = "post-completion" as const;
+    skipVerification = true; // Objective check - todos are data, not judgment
+
+    async detect(context: PostCompletionContext): Promise<HeuristicDetection> {
+        // Skip if agent has no todos at all
+        if (context.todos.length === 0) {
+            return { triggered: false };
+        }
+
+        // Skip if agent has pending delegations - they're legitimately waiting for delegated work
+        // to complete. Nagging about incomplete todos while waiting on delegations is confusing.
+        if (context.pendingDelegationCount > 0) {
+            return {
+                triggered: false,
+                reason: `Agent has ${context.pendingDelegationCount} pending delegation(s) - skipping todo check`,
+            };
+        }
+
+        // Find todos that are incomplete (pending or in_progress)
+        const incompleteTodos = context.todos.filter(
+            (t) => t.status === "pending" || t.status === "in_progress"
+        );
+
+        // No incomplete todos = agent is done
+        if (incompleteTodos.length === 0) {
+            return { triggered: false };
+        }
+
+        return {
+            triggered: true,
+            reason: `Agent has ${incompleteTodos.length} incomplete todo(s) (pending or in_progress)`,
+            evidence: {
+                incompleteTodos: incompleteTodos.map((t) => ({
+                    id: t.id,
+                    title: t.title,
+                    status: t.status,
+                })),
+                totalTodos: context.todos.length,
+            },
+        };
+    }
+
+    buildVerificationPrompt(_context: PostCompletionContext, _detection: HeuristicDetection): string {
+        // Not used since skipVerification is true
+        return "";
+    }
+
+    buildCorrectionMessage(context: PostCompletionContext, _verification: VerificationResult): string {
+        const incompleteTodos = context.todos.filter(
+            (t) => t.status === "pending" || t.status === "in_progress"
+        );
+
+        const todoList = incompleteTodos
+            .map((t) => `- [${t.status}] **${t.title}**${t.description ? `: ${t.description}` : ""}`)
+            .join("\n");
+
+        return `You have incomplete items in your todo list:
+
+${todoList}
+
+Would you like to address these before finishing your turn? If you're intentionally leaving them incomplete (waiting on delegation, user request, or other valid reasons), please confirm your intent.
+
+You can use \`todo_write\` to update item statuses if needed.`;
+    }
+
+    getCorrectionAction(_verification: VerificationResult): CorrectionAction {
+        return {
+            type: "suppress-publish",
+            reEngage: true, // Re-engage agent to address todos
+        };
+    }
+}

package/src/agents/supervision/heuristics/SilentAgentHeuristic.ts

@@ -0,0 +1,54 @@
+import { isDelegateToolName } from "@/agents/tool-names";
+import type { CorrectionAction, Heuristic, HeuristicDetection, PostCompletionContext, VerificationResult } from "../types";
+
+export class SilentAgentHeuristic implements Heuristic<PostCompletionContext> {
+  id = "silent-agent";
+  name = "Silent Agent Detection";
+  timing = "post-completion" as const;
+
+  async detect(context: PostCompletionContext): Promise<HeuristicDetection> {
+    const content = context.messageContent?.trim() || "";
+    const hasMeaningfulContent = content.length > 0;
+    const hasToolCalls = context.toolCallsMade.length > 0;
+
+    // Silent = no content AND no tool calls that would produce output
+    // Exception: delegate calls are ok since agent is waiting for delegation
+    const delegateCalls = context.toolCallsMade.filter((toolName) => isDelegateToolName(toolName));
+    const hasOnlyDelegateCalls = hasToolCalls && delegateCalls.length === context.toolCallsMade.length;
+
+    const isSilent = !hasMeaningfulContent && !hasOnlyDelegateCalls;
+
+    return {
+      triggered: isSilent,
+      reason: isSilent ? "Agent completed without generating any output or meaningful tool calls" : undefined,
+      evidence: {
+        messageContent: content.substring(0, 100),
+        toolCallsMade: context.toolCallsMade,
+      },
+    };
+  }
+
+  buildVerificationPrompt(context: PostCompletionContext, detection: HeuristicDetection): string {
+    const evidence = detection.evidence as { messageContent?: string } | undefined;
+    return `The agent "${context.agentSlug}" completed its turn without producing any visible output.
+This may indicate the agent failed to respond appropriately.
+
+Evidence:
+- Message content: "${evidence?.messageContent || "(empty)"}"
+- Tool calls: ${JSON.stringify(context.toolCallsMade)}
+
+Is this acceptable behavior or should the agent be prompted to respond?`;
+  }
+
+  buildCorrectionMessage(_context: PostCompletionContext, verification: VerificationResult): string {
+    return verification.correctionMessage ||
+      "You completed your turn without providing any response. Please provide a meaningful response to the user's request.";
+  }
+
+  getCorrectionAction(_verification: VerificationResult): CorrectionAction {
+    return {
+      type: "suppress-publish",
+      reEngage: true,
+    };
+  }
+}

package/src/agents/supervision/heuristics/index.ts

@@ -0,0 +1,5 @@
+export { HeuristicRegistry } from "./HeuristicRegistry";
+export { SilentAgentHeuristic } from "./SilentAgentHeuristic";
+export { DelegationClaimHeuristic } from "./DelegationClaimHeuristic";
+export { ConsecutiveToolsWithoutTodoHeuristic } from "./ConsecutiveToolsWithoutTodoHeuristic";
+export { PendingTodosHeuristic } from "./PendingTodosHeuristic";

package/src/agents/supervision/index.ts

@@ -0,0 +1,28 @@
+// Types
+export * from "./types";
+
+// Heuristics
+export { HeuristicRegistry } from "./heuristics";
+export {
+    SilentAgentHeuristic,
+    DelegationClaimHeuristic,
+    PendingTodosHeuristic,
+} from "./heuristics";
+
+// Services
+export { SupervisorLLMService, supervisorLLMService } from "./SupervisorLLMService";
+export {
+    SupervisorOrchestrator,
+    supervisorOrchestrator,
+    type SupervisionCheckResult,
+} from "./SupervisorOrchestrator";
+
+// Registration
+export { registerDefaultHeuristics, updateKnownAgentSlugs } from "./registerHeuristics";
+
+// Health Check
+export {
+    checkSupervisionHealth,
+    assertSupervisionHealth,
+    type SupervisionHealthCheckResult,
+} from "./supervisionHealthCheck";

package/src/agents/supervision/registerHeuristics.ts

@@ -0,0 +1,110 @@
+/**
+ * Register all default heuristics with the HeuristicRegistry
+ * This should be called during application startup
+ */
+import { logger } from "@/utils/logger";
+import {
+    HeuristicRegistry,
+    SilentAgentHeuristic,
+    DelegationClaimHeuristic,
+    ConsecutiveToolsWithoutTodoHeuristic,
+    PendingTodosHeuristic,
+} from "./heuristics";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("tenex.supervision");
+
+let registered = false;
+
+/**
+ * Register all default supervision heuristics
+ * Safe to call multiple times - will only register once
+ *
+ * IMPORTANT: This must be called during startup to enable supervision.
+ * Without registered heuristics, the supervision system will throw an error
+ * (fail-closed behavior to prevent silent supervision bypass).
+ */
+export function registerDefaultHeuristics(): void {
+    if (registered) {
+        // Routine re-registration check - use DEBUG to avoid log spam
+        logger.debug("[Supervision] Heuristics already registered, skipping re-registration", {
+            count: HeuristicRegistry.getInstance().size,
+            ids: HeuristicRegistry.getInstance().getAllIds(),
+        });
+        return;
+    }
+
+    const span = tracer.startSpan("supervision.register_default_heuristics");
+
+    try {
+        const registry = HeuristicRegistry.getInstance();
+        const sizeBefore = registry.size;
+
+        span.setAttribute("registry.size_before", sizeBefore);
+
+        // Register post-completion heuristics
+        registry.register(new SilentAgentHeuristic());
+        registry.register(new DelegationClaimHeuristic());
+        registry.register(new ConsecutiveToolsWithoutTodoHeuristic());
+        registry.register(new PendingTodosHeuristic());
+
+        registered = true;
+        const sizeAfter = registry.size;
+        const registeredIds = registry.getAllIds();
+
+        span.setAttributes({
+            "registry.size_after": sizeAfter,
+            "registry.heuristics_added": sizeAfter - sizeBefore,
+            "registry.ids": registeredIds.join(","),
+        });
+
+        span.addEvent("supervision.heuristics_registered", {
+            "count": sizeAfter,
+            "ids": registeredIds.join(","),
+        });
+
+        span.setStatus({ code: SpanStatusCode.OK });
+
+        // Use INFO level to ensure this is always visible in logs
+        logger.info("[Supervision] Successfully registered default heuristics", {
+            count: sizeAfter,
+            ids: registeredIds,
+            sizeBefore,
+            sizeAfter,
+        });
+    } catch (error) {
+        // Normalize error before recording
+        const normalizedError = error instanceof Error ? error : new Error(String(error));
+        span.recordException(normalizedError);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: "Failed to register heuristics" });
+        logger.error("[Supervision] FATAL: Failed to register default heuristics", normalizedError);
+        throw error;
+    } finally {
+        span.end();
+    }
+}
+
+/**
+ * Configure the DelegationClaimHeuristic with known agent slugs
+ * Should be called when agents are loaded/changed
+ */
+export function updateKnownAgentSlugs(slugs: string[]): void {
+    const registry = HeuristicRegistry.getInstance();
+    const heuristic = registry.get("delegation-claim") as DelegationClaimHeuristic | undefined;
+    if (heuristic) {
+        heuristic.setKnownAgentSlugs(slugs);
+        logger.debug("[Supervision] Updated known agent slugs", { count: slugs.length });
+    }
+}
+
+/**
+ * Reset registration state for testing purposes.
+ * This allows tests to verify fail-closed behavior by clearing heuristics
+ * and ensuring registerDefaultHeuristics() will run fresh.
+ *
+ * WARNING: Only use in tests. Never call in production code.
+ */
+export function resetRegistrationForTesting(): void {
+    registered = false;
+    HeuristicRegistry.getInstance().clear();
+}

package/src/agents/supervision/supervisionHealthCheck.ts

@@ -0,0 +1,123 @@
+/**
+ * Centralized supervision health check utility.
+ * Ensures consistent fail-closed validation across all supervision entry points.
+ *
+ * The supervision system uses a fail-closed approach: if heuristics aren't properly
+ * registered, the system should refuse to proceed rather than silently bypassing supervision.
+ */
+
+import { HeuristicRegistry } from "./heuristics/HeuristicRegistry";
+import { registerDefaultHeuristics } from "./registerHeuristics";
+import { logger } from "@/utils/logger";
+
+/**
+ * Result of a supervision health check.
+ */
+export interface SupervisionHealthCheckResult {
+    /** Whether the health check passed */
+    healthy: boolean;
+    /** Total number of registered heuristics */
+    registrySize: number;
+    /** Number of post-completion heuristics */
+    postCompletionCount: number;
+    /** IDs of all registered heuristics */
+    heuristicIds: string[];
+    /** Error message if unhealthy */
+    errorMessage?: string;
+}
+
+/**
+ * Perform a comprehensive supervision health check.
+ *
+ * This validates the CURRENT state of the registry:
+ * 1. Registry is not empty (CRITICAL - fail-closed)
+ * 2. Post-completion heuristics exist (CRITICAL - fail-closed)
+ *
+ * NOTE: This function does NOT register heuristics - callers should ensure
+ * registerDefaultHeuristics() has been called before checking health.
+ * This separation allows proper testing of fail-closed behavior.
+ *
+ * FAIL-CLOSED SEMANTICS:
+ * - Returns healthy=false if ANY critical condition is not met
+ * - Caller is responsible for acting on the result (throwing, logging, etc.)
+ *
+ * @returns Health check result with diagnostic information
+ */
+export function checkSupervisionHealth(): SupervisionHealthCheckResult {
+    const registry = HeuristicRegistry.getInstance();
+    const registrySize = registry.size;
+    const heuristicIds = registry.getAllIds();
+    const postCompletionCount = registry.getPostCompletionHeuristics().length;
+
+    // FAIL-CLOSED: Both conditions must be met
+    if (registrySize === 0) {
+        const errorMessage =
+            `FATAL: Supervision system has no heuristics registered! ` +
+            `This indicates a critical configuration error. ` +
+            `The system cannot proceed without supervision.`;
+
+        return {
+            healthy: false,
+            registrySize,
+            postCompletionCount,
+            heuristicIds,
+            errorMessage,
+        };
+    }
+
+    if (postCompletionCount === 0) {
+        const errorMessage =
+            `FATAL: No post-completion heuristics registered! ` +
+            `Registry has ${registrySize} total heuristics: [${heuristicIds.join(", ")}], ` +
+            `but none are post-completion type. ` +
+            `Supervision system is misconfigured - refusing to proceed without post-completion checks.`;
+
+        return {
+            healthy: false,
+            registrySize,
+            postCompletionCount,
+            heuristicIds,
+            errorMessage,
+        };
+    }
+
+    return {
+        healthy: true,
+        registrySize,
+        postCompletionCount,
+        heuristicIds,
+    };
+}
+
+/**
+ * Assert supervision health, throwing if unhealthy.
+ *
+ * This function:
+ * 1. Ensures heuristics are registered (calls registerDefaultHeuristics)
+ * 2. Performs health check
+ * 3. Throws if unhealthy
+ *
+ * Use this at startup or before executing completions to ensure
+ * fail-closed behavior is enforced consistently.
+ *
+ * @param context - Context string for error messages (e.g., "AgentExecutor", "ProjectRuntime")
+ * @throws Error if supervision health check fails
+ */
+export function assertSupervisionHealth(context: string): void {
+    // Ensure heuristics are registered before checking health
+    registerDefaultHeuristics();
+
+    const result = checkSupervisionHealth();
+
+    if (!result.healthy) {
+        const fullMessage = `[${context}] ${result.errorMessage}`;
+        logger.error(fullMessage);
+        throw new Error(fullMessage);
+    }
+
+    logger.debug(`[${context}] Supervision health check passed`, {
+        registrySize: result.registrySize,
+        postCompletionCount: result.postCompletionCount,
+        heuristicIds: result.heuristicIds,
+    });
+}