@tenex-chat/backend 0.9.1

package/src/agents/execution/MessageSyncer.ts

@@ -0,0 +1,100 @@
+import type { ModelMessage, ToolCallPart, ToolResultPart } from "ai";
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import { RALRegistry } from "@/services/ral";
+
+/**
+ * Syncs messages from AI SDK's step.messages to ConversationStore.
+ * Ensures ConversationStore never misses tool calls/results that the AI SDK tracked.
+ *
+ * This handles cases where tool-did-execute events don't fire (provider-dependent,
+ * e.g., Ollama doesn't emit tool-error chunks), ensuring tool results are never lost.
+ *
+ * Also clears tool tracking state as a fallback when tool results are observed
+ * without corresponding tool-did-execute events.
+ */
+export class MessageSyncer {
+    private conversationId: string;
+
+    constructor(
+        private conversationStore: ConversationStore,
+        private agentPubkey: string,
+        private ralNumber: number
+    ) {
+        this.conversationId = conversationStore.id;
+    }
+
+    /**
+     * Sync tool messages from AI SDK to ConversationStore.
+     * Call this at the start of prepareStep before rebuilding messages.
+     */
+    syncFromSDK(messages: ModelMessage[]): void {
+        for (const msg of messages) {
+            if (msg.role === "assistant" && Array.isArray(msg.content)) {
+                this.syncToolCalls(msg.content);
+            }
+            if (msg.role === "tool" && Array.isArray(msg.content)) {
+                this.syncToolResults(msg.content);
+            }
+        }
+    }
+
+    private syncToolCalls(content: unknown[]): void {
+        for (const part of content) {
+            if (this.isToolCallPart(part)) {
+                if (!this.conversationStore.hasToolCall(part.toolCallId)) {
+                    this.conversationStore.addMessage({
+                        pubkey: this.agentPubkey,
+                        ral: this.ralNumber,
+                        content: "",
+                        messageType: "tool-call",
+                        toolData: [part],
+                    });
+                }
+            }
+        }
+    }
+
+    private syncToolResults(content: unknown[]): void {
+        const ralRegistry = RALRegistry.getInstance();
+
+        for (const part of content) {
+            if (this.isToolResultPart(part)) {
+                if (!this.conversationStore.hasToolResult(part.toolCallId)) {
+                    this.conversationStore.addMessage({
+                        pubkey: this.agentPubkey,
+                        ral: this.ralNumber,
+                        content: "",
+                        messageType: "tool-result",
+                        toolData: [part],
+                    });
+                }
+
+                // Fallback: Clear tool from activeTools if it wasn't cleared by tool-did-execute.
+                // This handles cases where tool-did-execute doesn't fire (provider-dependent).
+                // If the tool was already cleared, this is a no-op.
+                ralRegistry.clearToolFallback(
+                    this.agentPubkey,
+                    this.conversationId,
+                    this.ralNumber,
+                    part.toolCallId
+                );
+            }
+        }
+    }
+
+    private isToolCallPart(part: unknown): part is ToolCallPart {
+        return (
+            typeof part === "object" &&
+            part !== null &&
+            (part as Record<string, unknown>).type === "tool-call"
+        );
+    }
+
+    private isToolResultPart(part: unknown): part is ToolResultPart {
+        return (
+            typeof part === "object" &&
+            part !== null &&
+            (part as Record<string, unknown>).type === "tool-result"
+        );
+    }
+}

package/src/agents/execution/PostCompletionChecker.ts

@@ -0,0 +1,278 @@
+/**
+ * Post-completion supervision checker for agent responses.
+ *
+ * Runs heuristics to detect suspicious agent behavior before publishing.
+ * This includes todo list compliance, delegation validation, and other
+ * behavioral checks defined in the supervision system.
+ */
+import {
+    supervisorOrchestrator,
+    updateKnownAgentSlugs,
+    type PostCompletionContext,
+} from "@/agents/supervision";
+import type { AgentInstance } from "@/agents/types";
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import type { CompleteEvent } from "@/llm/types";
+import { AgentEventDecoder } from "@/nostr/AgentEventDecoder";
+import { buildSystemPromptMessages } from "@/prompts/utils/systemPromptBuilder";
+import { NudgeService } from "@/services/nudge";
+import { getProjectContext } from "@/services/projects";
+import { RALRegistry } from "@/services/ral";
+import { getToolsObject } from "@/tools/registry";
+import type { FullRuntimeContext } from "./types";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { logger } from "@/utils/logger";
+import { PREFIX_LENGTH } from "@/utils/nostr-entity-parser";
+import { trace } from "@opentelemetry/api";
+
+export interface PostCompletionCheckResult {
+    /**
+     * Whether to suppress publishing and re-engage the agent
+     */
+    shouldReEngage: boolean;
+    /**
+     * Correction message to inject if re-engaging
+     */
+    correctionMessage?: string;
+    /**
+     * Whether a non-re-engaging message injection was queued
+     */
+    injectedMessage: boolean;
+}
+
+export interface PostCompletionCheckerConfig {
+    agent: AgentInstance;
+    context: FullRuntimeContext;
+    conversationStore: ConversationStore;
+    ralNumber: number;
+    completionEvent: CompleteEvent;
+}
+
+/**
+ * Run post-completion supervision check on agent response.
+ *
+ * @returns Result indicating whether to re-engage, inject messages, or proceed normally
+ */
+export async function checkPostCompletion(
+    config: PostCompletionCheckerConfig
+): Promise<PostCompletionCheckResult> {
+    const { agent, context, conversationStore, ralNumber, completionEvent } = config;
+    const ralRegistry = RALRegistry.getInstance();
+    const executionId = `${agent.pubkey}:${context.conversationId}:${ralNumber}`;
+
+    logger.debug("[PostCompletionChecker] Running supervision check", {
+        agent: agent.slug,
+        ralNumber,
+    });
+
+    // Check if we've exceeded max retries for supervision
+    if (supervisorOrchestrator.hasExceededMaxRetries(executionId)) {
+        logger.warn("[PostCompletionChecker] Supervision max retries exceeded, publishing anyway", {
+            agent: agent.slug,
+            ralNumber,
+        });
+        supervisorOrchestrator.clearState(executionId);
+        return { shouldReEngage: false, injectedMessage: false };
+    }
+
+    // Build supervision context
+    const projectContext = getProjectContext();
+
+    // Get tool calls from conversation store
+    const storeMessages = conversationStore?.getAllMessages() || [];
+    const toolCallsMade = storeMessages
+        .filter(m => m.ral === ralNumber && m.messageType === "tool-call" && m.toolData)
+        .flatMap(m => m.toolData?.map(td => {
+            if (td.type === "tool-call" && "toolName" in td) {
+                return td.toolName;
+            }
+            return undefined;
+        }).filter(Boolean) as string[] || []);
+
+    // Build the system prompt for context
+    const conversation = context.getConversation();
+
+    // Fetch nudge content if triggering event has nudge tags
+    const nudgeEventIds = AgentEventDecoder.extractNudgeEventIds(context.triggeringEvent);
+    const nudgeContent = nudgeEventIds.length > 0
+        ? await NudgeService.getInstance().fetchNudges(nudgeEventIds)
+        : "";
+
+    const systemPromptMessages = conversation ? await buildSystemPromptMessages({
+        agent,
+        project: projectContext.project,
+        conversation,
+        projectBasePath: context.projectBasePath,
+        workingDirectory: context.workingDirectory,
+        currentBranch: context.currentBranch,
+        availableAgents: Array.from(projectContext.agents.values()),
+        mcpManager: projectContext.mcpManager,
+        agentLessons: projectContext.agentLessons,
+        nudgeContent,
+    }) : [];
+    const systemPrompt = systemPromptMessages.map(m => m.message.content).join("\n\n");
+
+    // Update known agent slugs for delegation heuristic
+    updateKnownAgentSlugs(Array.from(projectContext.agents.values()).map(a => a.slug));
+
+    // Build conversation history
+    const conversationMessages = conversationStore
+        ? await conversationStore.buildMessagesForRal(agent.pubkey, ralNumber)
+        : [];
+
+    const toolNames = agent.tools || [];
+    const toolsObject = toolNames.length > 0 ? getToolsObject(toolNames, context) : {};
+
+    // Check todo state for supervision context
+    const todos = conversationStore
+        ? conversationStore.getTodos(agent.pubkey)
+        : [];
+    const hasBeenNudgedAboutTodos = conversationStore
+        ? conversationStore.hasBeenNudgedAboutTodos(agent.pubkey)
+        : false;
+
+    // Get pending delegation count from RALRegistry (conversation-wide, not RAL-scoped)
+    // We check ALL pending delegations for this conversation because a delegation from
+    // an earlier RAL that hasn't completed yet should still suppress the pending-todos heuristic
+    const pendingDelegations = ralRegistry.getConversationPendingDelegations(
+        agent.pubkey,
+        context.conversationId
+        // Note: ralNumber is intentionally omitted to get conversation-wide scope
+    );
+    const pendingDelegationCount = pendingDelegations.length;
+
+    // Emit telemetry only when pending delegations exist (avoids noisy zero-count events)
+    if (pendingDelegationCount > 0) {
+        // Cap delegation IDs to first 5 to prevent unbounded output
+        const maxDelegationsToLog = 5;
+        const delegationIds = pendingDelegations
+            .slice(0, maxDelegationsToLog)
+            .map(d => d.delegationConversationId.substring(0, PREFIX_LENGTH));
+        const truncatedIndicator = pendingDelegationCount > maxDelegationsToLog
+            ? ` (+${pendingDelegationCount - maxDelegationsToLog} more)`
+            : "";
+
+        logger.debug("[PostCompletionChecker] Pending delegations detected; pending-todos heuristic may be suppressed", {
+            agent: agent.slug,
+            pendingDelegationCount,
+            delegationIds: `[${delegationIds.join(", ")}]${truncatedIndicator}`,
+        });
+
+        trace.getActiveSpan()?.addEvent("executor.supervision_pending_delegations", {
+            "agent.slug": agent.slug,
+            "agent.pubkey": agent.pubkey.substring(0, PREFIX_LENGTH),
+            "conversation.id": shortenConversationId(context.conversationId),
+            "ral.number": ralNumber,
+            "delegation.pending_count": pendingDelegationCount,
+        });
+    }
+
+    const supervisionContext: PostCompletionContext = {
+        agentSlug: agent.slug,
+        agentPubkey: agent.pubkey,
+        messageContent: completionEvent.message || "",
+        toolCallsMade,
+        systemPrompt,
+        conversationHistory: conversationMessages,
+        availableTools: toolsObject,
+        hasBeenNudgedAboutTodos,
+        todos: todos.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            description: t.description,
+        })),
+        pendingDelegationCount,
+    };
+
+    const supervisionResult = await supervisorOrchestrator.checkPostCompletion(supervisionContext, executionId);
+
+    if (supervisionResult.hasViolation && supervisionResult.correctionAction) {
+        trace.getActiveSpan()?.addEvent("executor.supervision_violation", {
+            "ral.number": ralNumber,
+            "heuristic.id": supervisionResult.heuristicId || "unknown",
+            "action.type": supervisionResult.correctionAction.type,
+        });
+
+        logger.info("[PostCompletionChecker] Supervision detected violation", {
+            agent: agent.slug,
+            heuristic: supervisionResult.heuristicId,
+            actionType: supervisionResult.correctionAction.type,
+        });
+
+        // Mark agent as nudged if this was the todo nudge heuristic
+        if (supervisionResult.heuristicId === "consecutive-tools-without-todo" && conversationStore) {
+            conversationStore.setNudgedAboutTodos(agent.pubkey);
+            await conversationStore.save();
+        }
+
+        if (supervisionResult.correctionAction.type === "suppress-publish" &&
+            supervisionResult.correctionAction.reEngage) {
+            // Add telemetry for supervision correction diagnosis
+            trace.getActiveSpan()?.addEvent("executor.supervision_correction", {
+                "has_message": !!supervisionResult.correctionAction.message,
+                "message_length": supervisionResult.correctionAction.message?.length || 0,
+                "heuristic.id": supervisionResult.heuristicId || "unknown",
+                "action.type": supervisionResult.correctionAction.type,
+                "action.reEngage": supervisionResult.correctionAction.reEngage,
+            });
+
+            // Increment retry count
+            supervisorOrchestrator.incrementRetryCount(executionId);
+
+            // Mark this heuristic as enforced so it won't fire again in this RAL
+            if (supervisionResult.heuristicId) {
+                supervisorOrchestrator.markHeuristicEnforced(executionId, supervisionResult.heuristicId);
+            }
+
+            // Inject correction message as ephemeral user message
+            if (supervisionResult.correctionAction.message) {
+                ralRegistry.queueUserMessage(
+                    agent.pubkey,
+                    context.conversationId,
+                    ralNumber,
+                    supervisionResult.correctionAction.message,
+                    { ephemeral: true }
+                );
+            }
+
+            return {
+                shouldReEngage: true,
+                correctionMessage: supervisionResult.correctionAction.message,
+                injectedMessage: false,
+            };
+        } else if (supervisionResult.correctionAction.type === "inject-message" &&
+            supervisionResult.correctionAction.message) {
+            // Store message for agent's NEXT turn (not current RAL).
+            // Using deferredInjections instead of ralRegistry.queueSystemMessage() ensures
+            // this does NOT count as "outstanding work" and allows the agent to complete()
+            // properly. The message will be picked up at the start of the agent's next turn.
+            conversationStore.addDeferredInjection({
+                targetPubkey: agent.pubkey,
+                role: "system",
+                content: supervisionResult.correctionAction.message,
+                queuedAt: Date.now(),
+                source: `supervision:${supervisionResult.heuristicId || "unknown"}`,
+            });
+            await conversationStore.save();
+
+            trace.getActiveSpan()?.addEvent("executor.supervision_deferred_injection", {
+                "ral.number": ralNumber,
+                "heuristic.id": supervisionResult.heuristicId || "unknown",
+                "message_length": supervisionResult.correctionAction.message.length,
+            });
+
+            return {
+                shouldReEngage: false,
+                injectedMessage: true,
+            };
+        }
+    } else {
+        logger.debug("[PostCompletionChecker] Supervision check passed", {
+            agent: agent.slug,
+            ralNumber,
+        });
+    }
+
+    return { shouldReEngage: false, injectedMessage: false };
+}

package/src/agents/execution/ProgressMonitor.ts

@@ -0,0 +1,50 @@
+import { logger } from "@/utils/logger";
+import type { LanguageModel } from "ai";
+import { generateText } from "ai";
+
+export class ProgressMonitor {
+    private stepCount = 0;
+    private readonly REVIEW_THRESHOLD = 50;
+
+    constructor(private readonly reviewModel: LanguageModel) {}
+
+    async check(toolNames: string[]): Promise<boolean> {
+        this.stepCount++;
+
+        if (this.stepCount < this.REVIEW_THRESHOLD) {
+            return true;
+        }
+
+        this.stepCount = 0;
+
+        try {
+            const toolCallSummary = toolNames.map((name, i) => `${i + 1}. ${name}`).join("\n");
+
+            const result = await generateText({
+                model: this.reviewModel,
+                messages: [
+                    {
+                        role: "user",
+                        content: `Review these ${toolNames.length} tool calls. Is the agent making progress or stuck?\n\n${toolCallSummary}\n\nRespond with only "continue" or "stop":`,
+                    },
+                ],
+                maxOutputTokens: 10,
+                temperature: 0,
+            });
+
+            const shouldContinue = result.text.trim().toLowerCase().includes("continue");
+
+            logger.info("[ProgressMonitor] Review completed", {
+                shouldContinue,
+                toolCallCount: toolNames.length,
+            });
+
+            return shouldContinue;
+        } catch (error) {
+            logger.error("[ProgressMonitor] Review failed, stopping", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+}

package/src/agents/execution/RALResolver.ts

@@ -0,0 +1,177 @@
+/**
+ * RAL (Request/Agent Lifecycle) resolution for agent execution.
+ *
+ * Handles the logic of finding or creating a RAL for an execution:
+ * - Check for resumable RAL (completed delegations ready to continue)
+ * - Check for RAL with queued injections
+ * - Create new RAL if none found
+ */
+import type { Span } from "@opentelemetry/api";
+import { RALRegistry } from "@/services/ral";
+import { ConversationStore } from "@/conversations/ConversationStore";
+import type { DelegationMarker } from "@/conversations/types";
+
+export interface RALResolutionContext {
+    agentPubkey: string;
+    conversationId: string;
+    /** Project ID for multi-project isolation in daemon mode */
+    projectId: string;
+    triggeringEventId: string;
+    span: Span;
+}
+
+export interface RALResolutionResult {
+    ralNumber: number;
+    isResumption: boolean;
+    /** Delegation markers that need to be published to Nostr */
+    markersToPublish?: Array<{
+        delegationConversationId: string;
+        recipientPubkey: string;
+        parentConversationId: string;
+        status: "completed" | "aborted";
+        completedAt: number;
+        abortReason?: string;
+    }>;
+}
+
+/**
+ * Resolve which RAL to use for this execution.
+ *
+ * Priority:
+ * 1. Resumable RAL - has completed delegations ready to continue
+ * 2. Injection RAL - has queued injections
+ * 3. New RAL - create fresh for this execution
+ */
+export async function resolveRAL(ctx: RALResolutionContext): Promise<RALResolutionResult> {
+    const { agentPubkey, conversationId, projectId, triggeringEventId, span } = ctx;
+    const ralRegistry = RALRegistry.getInstance();
+
+    // Check for a resumable RAL (one with completed delegations ready to continue)
+    const resumableRal = ralRegistry.findResumableRAL(agentPubkey, conversationId);
+
+    // Also check for RAL with queued injections
+    const injectionRal = !resumableRal
+        ? ralRegistry.findRALWithInjections(agentPubkey, conversationId)
+        : undefined;
+
+    let ralNumber: number;
+    let isResumption = false;
+    let markersToPublish: Array<{
+        delegationConversationId: string;
+        recipientPubkey: string;
+        parentConversationId: string;
+        status: "completed" | "aborted";
+        completedAt: number;
+        abortReason?: string;
+    }> = [];
+
+    if (resumableRal) {
+        // Resume existing RAL instead of creating a new one
+        ralNumber = resumableRal.ralNumber;
+        isResumption = true;
+
+        // Get delegations from conversation storage
+        const completedDelegations = ralRegistry.getConversationCompletedDelegations(
+            agentPubkey, conversationId, resumableRal.ralNumber
+        );
+        const pendingDelegations = ralRegistry.getConversationPendingDelegations(
+            agentPubkey, conversationId, resumableRal.ralNumber
+        );
+
+        // Get the parent conversation store to update/insert markers
+        const parentStore = ConversationStore.get(conversationId);
+
+        // Update delegation markers for each completed delegation (or create if not found)
+        // Markers are expanded lazily when building messages
+        if (parentStore) {
+            for (const completion of completedDelegations) {
+                // Try to update existing pending marker first
+                const updated = parentStore.updateDelegationMarker(
+                    completion.delegationConversationId,
+                    {
+                        status: completion.status,
+                        completedAt: completion.completedAt,
+                        abortReason: completion.status === "aborted" ? completion.abortReason : undefined,
+                    }
+                );
+
+                // If no pending marker found, create a new one (backward compatibility)
+                if (!updated) {
+                    const marker: DelegationMarker = {
+                        delegationConversationId: completion.delegationConversationId,
+                        recipientPubkey: completion.recipientPubkey,
+                        parentConversationId: conversationId,
+                        completedAt: completion.completedAt,
+                        status: completion.status,
+                        abortReason: completion.status === "aborted" ? completion.abortReason : undefined,
+                    };
+                    parentStore.addDelegationMarker(marker, agentPubkey, ralNumber);
+                }
+
+                // Collect markers to publish to Nostr
+                markersToPublish.push({
+                    delegationConversationId: completion.delegationConversationId,
+                    recipientPubkey: completion.recipientPubkey,
+                    parentConversationId: conversationId,
+                    status: completion.status,
+                    completedAt: completion.completedAt,
+                    abortReason: completion.status === "aborted" ? completion.abortReason : undefined,
+                });
+            }
+
+            // Save the store after adding/updating markers
+            await parentStore.save();
+        }
+
+        // Separate counts for telemetry
+        const abortedCount = completedDelegations.filter(d => d.status === "aborted").length;
+        const successfulCount = completedDelegations.filter(d => d.status !== "aborted").length;
+
+        // Clear completed delegations after inserting markers
+        // This prevents re-processing on subsequent executions
+        ralRegistry.clearCompletedDelegations(agentPubkey, conversationId, ralNumber);
+
+        span.addEvent("executor.ral_resumed", {
+            "ral.number": ralNumber,
+            "delegation.completed_count": successfulCount,
+            "delegation.aborted_count": abortedCount,
+            "delegation.pending_count": pendingDelegations.length,
+            "delegation.markers_inserted": completedDelegations.length,
+        });
+    } else if (injectionRal) {
+        // Resume RAL with queued injections
+        ralNumber = injectionRal.ralNumber;
+        isResumption = true;
+
+        const injectionRalPending = ralRegistry.getConversationPendingDelegations(
+            agentPubkey, conversationId, injectionRal.ralNumber
+        );
+        span.addEvent("executor.ral_resumed_for_injection", {
+            "ral.number": ralNumber,
+            "injection.count": injectionRal.queuedInjections.length,
+            pending_delegations: injectionRalPending.length,
+        });
+    } else {
+        // Create a new RAL for this execution
+        // Pass projectId for multi-project isolation and trace context for stop event correlation
+        const spanContext = span.spanContext();
+        ralNumber = ralRegistry.create(
+            agentPubkey,
+            conversationId,
+            projectId,
+            triggeringEventId,
+            { traceId: spanContext.traceId, spanId: spanContext.spanId }
+        );
+    }
+
+    span.setAttributes({
+        "ral.number": ralNumber,
+        "ral.is_resumption": isResumption,
+    });
+
+    return {
+        ralNumber,
+        isResumption,
+        markersToPublish: markersToPublish.length > 0 ? markersToPublish : undefined,
+    };
+}