neoagent 2.3.1-beta.0 → 2.3.1-beta.100

package/server/services/ai/engine.js

@@ -37,9 +37,17 @@ const {
   buildInterimSignature,
   normalizeInterimKind,
 } = require('./interim');
-
-const MAX_CONSECUTIVE_TOOL_FAILURES = 3;
-const WIDGET_REFRESH_MAX_ITERATIONS = 6;
+const { recordRunEvent } = require('./runEvents');
+const {
+  buildDeliverableWorkflowGuidance,
+  DeliverableValidationError,
+  extractArtifactsFromResult,
+  getDeliverableWorkflow,
+  selectDeliverableWorkflow,
+  validateDeliverableExecution,
+} = require('./deliverables');
+const { buildLoopPolicy, resolveToolResultLimits } = require('./loopPolicy');
+const { globalHooks } = require('./hooks');
 
 function generateTitle(task) {
   if (!task || typeof task !== 'string') return 'Untitled';
@@ -72,11 +80,12 @@ function buildSkipTaskAnalysisResult(forceMode) {
   };
 }
 
-function buildAnalyzeTaskFallback(forceMode) {
+function buildAnalyzeTaskFallback(forceMode, userMessage = '') {
   return {
     mode: forceMode || 'execute',
     verification_need: 'light',
     planning_depth: planningDepthForForceMode(forceMode),
+    goal: userMessage ? String(userMessage).trim().slice(0, 300) : '',
   };
 }
 
@@ -640,10 +649,10 @@ class AgentEngine {
     this.activeRuns = new Map();
     this.subagents = new Map();
     this.app = services.app || null;
-    this.cliExecutor = services.cliExecutor || null;
     this.browserController = services.browserController || null;
     this.androidController = services.androidController || null;
     this.runtimeManager = services.runtimeManager || null;
+    this.workspaceManager = services.workspaceManager || null;
     this.messagingManager = services.messagingManager || null;
     this.mcpManager = services.mcpManager || services.mcpClient || null;
     this.skillRunner = services.skillRunner || null;
@@ -675,6 +684,54 @@ class AgentEngine {
       .run(JSON.stringify(next), runId);
   }
 
+  recordRunEvent(userId, runId, eventType, payload = {}, options = {}) {
+    try {
+      return recordRunEvent({
+        runId,
+        userId,
+        agentId: options.agentId || null,
+        eventType,
+        requestId: options.requestId || null,
+        stepId: options.stepId || null,
+        payload,
+      });
+    } catch {
+      return null;
+    }
+  }
+
+  async persistDeliverableMemory(userId, runId, agentId, deliverableResult) {
+    if (!this.memoryManager?.saveMemory || !deliverableResult?.summary) return;
+    try {
+      await this.memoryManager.saveMemory(
+        userId,
+        deliverableResult.summary,
+        'tasks',
+        deliverableResult.validation?.status === 'passed' ? 7 : 5,
+        {
+          agentId,
+          sourceRef: {
+            sourceType: 'deliverable_run',
+            sourceId: runId,
+            sourceLabel: deliverableResult.type || 'deliverable',
+          },
+          metadata: {
+            deliverableType: deliverableResult.type,
+            status: deliverableResult.status,
+            artifactCount: Array.isArray(deliverableResult.artifacts)
+              ? deliverableResult.artifacts.length
+              : 0,
+            artifacts: Array.isArray(deliverableResult.artifacts)
+              ? deliverableResult.artifacts.slice(0, 6)
+              : [],
+          },
+        },
+      );
+    } catch (error) {
+      console.error('[Engine] Failed to persist deliverable memory:', error?.message || error);
+    }
+  }
+
   async publishInterimUpdate({
     userId,
     runId,
@@ -686,6 +743,7 @@ class AgentEngine {
     content,
     kind,
     expectsReply = false,
+    deferFollowUp = false,
   } = {}) {
     const runMeta = this.getRunMeta(runId);
     if (!runMeta || runMeta.aborted) {
@@ -715,6 +773,9 @@ class AgentEngine {
       kind: normalizedKind,
       expectsReply,
     });
+    if (deferFollowUp === true) {
+      metadata.defer_follow_up = true;
+    }
     const createdAt = new Date().toISOString();
 
     if (triggerSource === 'messaging') {
@@ -739,6 +800,7 @@ class AgentEngine {
         content: normalizedContent,
         kind: normalizedKind,
         expectsReply,
+        deferFollowUp,
       });
     } else {
       db.prepare(
@@ -758,6 +820,7 @@ class AgentEngine {
       content: normalizedContent,
       kind: normalizedKind,
       expectsReply: expectsReply === true,
+      deferFollowUp: deferFollowUp === true,
       createdAt,
     });
     runMeta.lastInterimMessage = normalizedContent;
@@ -767,6 +830,7 @@ class AgentEngine {
       content: normalizedContent,
       kind: normalizedKind,
       expectsReply: expectsReply === true,
+      deferFollowUp: deferFollowUp === true,
       triggerSource,
       platform: triggerSource === 'messaging' ? platform : 'web',
     });
@@ -783,6 +847,7 @@ class AgentEngine {
       latestInterim: {
         kind: normalizedKind,
         expectsReply: expectsReply === true,
+        deferFollowUp: deferFollowUp === true,
         content: normalizedContent,
         createdAt,
       },
@@ -795,6 +860,7 @@ class AgentEngine {
       sent: true,
       kind: normalizedKind,
       expectsReply: expectsReply === true,
+      deferFollowUp: deferFollowUp === true,
       content: normalizedContent,
       terminal: terminalInterim,
     };
@@ -898,6 +964,7 @@ class AgentEngine {
     tools,
     capabilityHealth,
     forceMode,
+    userMessage,
     options,
   }) {
     const summary = summarizeCapabilityHealth(capabilityHealth);
@@ -913,7 +980,7 @@ class AgentEngine {
       }),
       maxTokens: 1100,
       normalize: normalizeTaskAnalysis,
-      fallback: buildAnalyzeTaskFallback(forceMode),
+      fallback: buildAnalyzeTaskFallback(forceMode, userMessage),
       reasoningEffort: this.getReasoningEffort(providerName, options),
     });
 
@@ -966,6 +1033,7 @@ class AgentEngine {
     toolExecutions,
     lastReply,
     triggerSource,
+    messagingSent,
     iteration,
     maxIterations,
     options,
@@ -995,9 +1063,11 @@ class AgentEngine {
         '- A progress update is not complete.',
         '- A single failed tool attempt is not blocked if another safe retry, verification step, or alternative path remains.',
         '- A tool-specific API error, timeout, rate limit, or missing result inside this run is usually "continue", not "blocked", if any other available tool could still make progress.',
-        triggerSource === 'messaging'
-          ? '- For messaging, do not stop on a partial status message. Continue unless the task is actually complete or externally blocked. If you already asked for missing user input, choose "blocked" and wait.'
-          : '- Do not stop just because you wrote a status update. Continue unless the task is actually complete or externally blocked.',
+        triggerSource === 'messaging' && messagingSent
+          ? '- A reply was already delivered to the user via send_message. Use "complete" unless there is concrete remaining work (e.g., a tool call you still need to make) before the task is truly done. Do not send follow-up elaborations or re-introductions.'
+          : triggerSource === 'messaging'
+            ? '- For messaging, do not stop on a partial status message. Continue unless the task is actually complete or externally blocked. If you already asked for missing user input, choose "blocked" and wait.'
+            : '- Do not stop just because you wrote a status update. Continue unless the task is actually complete or externally blocked.',
         analysis?.goal ? `Goal: ${analysis.goal}` : '',
         successCriteria.length > 0 ? `Success criteria:\n${successCriteria.map((item, index) => `${index + 1}. ${item}`).join('\n')}` : '',
         `Current iteration: ${iteration} of ${maxIterations}.`,
@@ -1314,8 +1384,10 @@ class AgentEngine {
     const runMeta = this.getRunMeta(runId);
     if (!runMeta || !pid) return;
     runMeta.toolPids.add(pid);
-    if (runMeta.aborted && this.cliExecutor) {
-      this.cliExecutor.kill(pid, 'aborted');
+    if (runMeta.aborted) {
+      if (this.runtimeManager && typeof this.runtimeManager.killCommand === 'function') {
+        void this.runtimeManager.killCommand(runMeta.userId, pid, 'aborted');
+      }
     }
   }
 
@@ -1325,11 +1397,8 @@ class AgentEngine {
     runMeta.toolPids.delete(pid);
   }
 
-  getIterationLimit(triggerType, aiSettings, options = {}) {
-    if (triggerType === 'subagent') return aiSettings.subagent_max_iterations;
-    if (options.widgetId) return Math.min(this.maxIterations, WIDGET_REFRESH_MAX_ITERATIONS);
-    return this.maxIterations;
-  }
+  // getIterationLimit() removed — use buildLoopPolicy() directly.
+  // maxIterations is derived in runWithModel from loopPolicy.maxIterations.
 
   getReasoningEffort(providerName, options = {}) {
     if (providerName === 'google') return undefined;
@@ -1468,8 +1537,11 @@ class AgentEngine {
       1,
       Number(options.historyWindow || aiSettings.chat_history_window) || aiSettings.chat_history_window,
     );
-    const toolReplayBudget = aiSettings.tool_replay_budget_chars;
-    const maxIterations = this.getIterationLimit(triggerType, aiSettings, options);
+    // loopPolicy is built after task analysis so analysisMode can be passed in;
+    // we build a provisional policy now (with default mode) and rebuild after
+    // analysis when the mode is known. See the post-analysis policy rebuild below.
+    let loopPolicy = buildLoopPolicy(aiSettings, triggerType, 'execute', options);
+    let maxIterations = loopPolicy.maxIterations;
     const providerStatusConfig = {
       agentId,
       onStatus: (status) => {
@@ -1524,6 +1596,12 @@ class AgentEngine {
       toolPids: new Set(),
     });
     this.emit(userId, 'run:start', { runId, agentId, title: runTitle, model, triggerType, triggerSource });
+    this.recordRunEvent(userId, runId, 'run_started', {
+      title: runTitle,
+      model,
+      triggerType,
+      triggerSource,
+    }, { agentId });
     console.info(
       `[Run ${shortenRunId(runId)}] started trigger=${triggerSource} type=${triggerType} model=${model} title=${summarizeForLog(runTitle, 120)}`
     );
@@ -1542,6 +1620,7 @@ class AgentEngine {
       agentId,
       triggerType,
       triggerSource,
+      widgetId: options.widgetId || null,
     });
     const mcpManager = app?.locals?.mcpManager || app?.locals?.mcpClient || this.mcpManager;
     const integrationManager = app?.locals?.integrationManager || null;
@@ -1583,6 +1662,11 @@ class AgentEngine {
     if (threadStateMessage) {
       messages.push({ role: 'system', content: threadStateMessage });
     }
+    this.recordRunEvent(userId, runId, 'memory_injected', {
+      hasRecallContext: Boolean(recallMsg),
+      hasThreadState: Boolean(threadStateMessage),
+      recallPreview: recallMsg ? String(recallMsg).slice(0, 240) : '',
+    }, { agentId });
     messages.push(this.buildUserMessage(userMessage, options));
     messages = sanitizeConversationMessages(messages);
 
@@ -1602,6 +1686,10 @@ class AgentEngine {
     let analysis = null;
     let plan = null;
     let verification = null;
+    let deliverableWorkflow = null;
+    let deliverablePlan = null;
+    let deliverableArtifacts = [];
+    let deliverableValidation = null;
     let directAnswerEligible = false;
     let analysisUsage = 0;
 
@@ -1617,11 +1705,15 @@ class AgentEngine {
           tools,
           capabilityHealth,
           forceMode: options.forceMode || null,
+          userMessage,
           options: { ...options, triggerSource },
         });
         analysisUsage = analysisResult.usage || 0;
         totalTokens += analysisUsage;
         analysis = applyForcedAnalysisMode({ ...analysisResult.analysis }, options.forceMode);
+        if (!analysis.goal && userMessage) {
+          analysis.goal = String(userMessage).trim().slice(0, 300);
+        }
         analysis.mode = promoteAnalysisMode(analysis.mode, {
           verificationNeed: analysis.verification_need,
           freshnessRisk: analysis.freshness_risk,
@@ -1652,6 +1744,62 @@ class AgentEngine {
           ...analysis,
           capabilitySummary,
         });
+
+      }
+
+      // Rebuild loop policy with the resolved analysis mode. Runs in both the
+      // normal path and the skipTaskAnalysis path so that forceMode='plan_execute'
+      // (or any mode set by buildSkipTaskAnalysisResult) raises the iteration
+      // ceiling correctly.
+      loopPolicy = buildLoopPolicy(aiSettings, triggerType, analysis.mode || 'execute', options);
+      maxIterations = loopPolicy.maxIterations;
+
+      if (options.skipDeliverableWorkflow !== true) {
+        const deliverableSelectionResult = await selectDeliverableWorkflow({
+          engine: this,
+          provider,
+          providerName,
+          model,
+          messages,
+          tools,
+          options,
+        });
+        totalTokens += deliverableSelectionResult.usage || 0;
+        const selectedWorkflow = getDeliverableWorkflow(deliverableSelectionResult.selection.type);
+        if (selectedWorkflow?.canHandle(deliverableSelectionResult.selection)) {
+          deliverableWorkflow = {
+            workflow: selectedWorkflow,
+            selection: deliverableSelectionResult.selection,
+            request: selectedWorkflow.normalizeRequest({
+              ...deliverableSelectionResult.selection,
+              userMessage,
+            }),
+          };
+          deliverablePlan = selectedWorkflow.buildExecutionPlan(deliverableWorkflow.request, {
+            analysis,
+            tools,
+            options,
+          });
+          await selectedWorkflow.run(deliverablePlan, {
+            engine: this,
+            userId,
+            runId,
+            agentId,
+            app,
+          });
+          this.persistRunMetadata(runId, {
+            deliverableWorkflow: {
+              ...deliverableWorkflow.selection,
+              plan: deliverablePlan,
+            },
+          });
+          this.recordRunEvent(userId, runId, 'deliverable_workflow_selected', {
+            type: deliverableWorkflow.selection.type,
+            confidence: deliverableWorkflow.selection.confidence,
+            goal: deliverableWorkflow.selection.goal,
+            requestedOutputs: deliverableWorkflow.selection.requestedOutputs,
+          }, { agentId });
+        }
       }
 
       if (analysis.mode === 'plan_execute') {
@@ -1697,6 +1845,17 @@ class AgentEngine {
           capabilityHealth: capabilitySummary,
         }),
       });
+      if (deliverablePlan) {
+        messages.push({
+          role: 'system',
+          content: buildDeliverableWorkflowGuidance(deliverablePlan),
+        });
+        this.recordRunEvent(userId, runId, 'deliverable_execution_started', {
+          type: deliverableWorkflow?.selection?.type,
+          preferredTools: deliverablePlan.preferredTools || [],
+          expectedOutputs: deliverablePlan.expectedOutputs || [],
+        }, { agentId });
+      }
       messages = sanitizeConversationMessages(messages);
 
       directAnswerEligible = isDirectAnswerEligibleAnalysis(analysis)
@@ -1712,10 +1871,15 @@ class AgentEngine {
         }
       }
 
+      // BUG FIX: consecutiveToolFailures was previously declared INSIDE the
+      // while loop (resetting each iteration). It is now tracked across the
+      // full run so the failure guard fires correctly after 5 consecutive failures
+      // regardless of which iteration they fall in.
+      let consecutiveToolFailures = 0;
+
       while (!directAnswerEligible && iteration < maxIterations) {
         if (this.isRunStopped(runId)) break;
         iteration++;
-        let consecutiveToolFailures = 0;
 
         const steeringAtLoopStart = this.applyQueuedSteering(runId, messages, {
           userId,
@@ -1726,7 +1890,7 @@ class AgentEngine {
 
         let metrics = this.estimatePromptMetrics(messages, tools);
         const contextWindow = provider.getContextWindow(model);
-        if (metrics.totalEstimatedTokens > contextWindow * 0.85) {
+        if (metrics.totalEstimatedTokens > contextWindow * loopPolicy.compactionThreshold) {
           messages = await compact(messages, provider, model, contextWindow);
           messages = sanitizeConversationMessages(messages);
           this.emit(userId, 'run:compaction', { runId, iteration });
@@ -1736,6 +1900,10 @@ class AgentEngine {
         promptMetrics = this.mergePromptMetrics(promptMetrics, metrics, iteration, tools.length);
         this.persistPromptMetrics(runId, promptMetrics).catch(() => { });
         this.emit(userId, 'run:thinking', { runId, iteration });
+        this.recordRunEvent(userId, runId, 'model_turn_started', {
+          iteration,
+          toolCount: tools.length,
+        }, { agentId });
 
         let response;
         let responseModel = model;
@@ -1813,7 +1981,7 @@ class AgentEngine {
           const isFatalModelError = /no ai providers? are currently available|missing an api key|disabled in settings|unauthorized|forbidden|authentication failed/i
             .test(modelError);
 
-          if (!isFatalModelError && modelFailureRecoveries < 2) {
+          if (!isFatalModelError && modelFailureRecoveries < loopPolicy.maxModelFailureRecoveries) {
             modelFailureRecoveries += 1;
             failedStepCount += 1;
             const failedModel = model;
@@ -1869,6 +2037,12 @@ class AgentEngine {
           }
         }
 
+        this.recordRunEvent(userId, runId, 'model_turn_completed', {
+          iteration,
+          toolCallCount: response.toolCalls?.length || 0,
+          contentPreview: String(lastContent || streamContent || '').slice(0, 240),
+        }, { agentId });
+
         const assistantMessage = { role: 'assistant', content: lastContent };
         if (response.toolCalls?.length) assistantMessage.tool_calls = response.toolCalls;
         if (response.providerContentBlocks?.length) assistantMessage.providerContentBlocks = response.providerContentBlocks;
@@ -1919,6 +2093,7 @@ class AgentEngine {
               toolExecutions,
               lastReply: lastContent,
               triggerSource,
+              messagingSent,
               iteration,
               maxIterations,
               options,
@@ -1955,6 +2130,44 @@ class AgentEngine {
             toolArgs = {};
           }
 
+          // ── task_complete: AI explicitly signals the task is fully done ──
+          // Handle before DB insert / before_tool_call hook — this is not a
+          // regular tool execution, it is a loop-exit signal.
+          if (toolName === 'task_complete') {
+            const finalMessage = String(toolArgs.message || '').trim();
+            this.recordRunEvent(userId, runId, 'task_complete_signaled', {
+              confidence: toolArgs.confidence || 'high',
+              iteration,
+              messageLength: finalMessage.length,
+            }, { agentId });
+            console.info(
+              `[Run ${shortenRunId(runId)}] task_complete signaled at iteration=${iteration} confidence=${toolArgs.confidence || 'high'}`
+            );
+            // Always honor task_complete as a stop signal, even with no message.
+            lastContent = finalMessage; // empty string is valid; downstream handles it
+            directAnswerEligible = true;
+            break; // exit the for-loop; the while condition will also exit
+          }
+
+          // ── before_tool_call hook ──
+          // Plugins can block a tool call (e.g. security policy) or mutate args.
+          if (globalHooks.has('before_tool_call')) {
+            const hookCtx = { toolName, toolArgs, runId, userId, agentId, iteration };
+            const hookResult = await globalHooks.run('before_tool_call', hookCtx);
+            if (hookResult.block) {
+              console.warn(`[Run ${shortenRunId(runId)}] before_tool_call hook blocked tool=${toolName}`);
+              // Treat as a soft skip — add a skipped tool message so the model knows
+              messages.push({
+                role: 'tool',
+                name: toolName,
+                tool_call_id: toolCall.id,
+                content: JSON.stringify({ tool: toolName, status: 'skipped', reason: 'Blocked by policy.' }),
+              });
+              continue;
+            }
+            if (hookResult.toolArgs) toolArgs = hookResult.toolArgs;
+          }
+
           db.prepare('INSERT INTO agent_steps (id, run_id, step_index, type, description, status, tool_name, tool_input, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime(\'now\'))')
             .run(stepId, runId, stepIndex, this.getStepType(toolName), `${toolName}: ${JSON.stringify(toolArgs).slice(0, 200)} `, 'running', toolName, JSON.stringify(toolArgs));
 
@@ -1962,6 +2175,12 @@ class AgentEngine {
             runId, stepId, stepIndex, toolName, toolArgs,
             type: this.getStepType(toolName)
           });
+          this.recordRunEvent(userId, runId, 'tool_started', {
+            stepIndex,
+            toolName,
+            toolArgs,
+            type: this.getStepType(toolName),
+          }, { agentId, stepId });
           console.info(
             `[Run ${shortenRunId(runId)}] step=${stepIndex} start tool=${toolName} args=${summarizeForLog(toolArgs)}`
           );
@@ -1996,11 +2215,24 @@ class AgentEngine {
               .run(stepStatus, JSON.stringify(toolResult).slice(0, 20000), toolErrorMessage || null, screenshotPath, stepId);
             if (toolErrorMessage) {
               this.emit(userId, 'run:tool_end', { runId, stepId, toolName, error: toolErrorMessage, result: toolResult, screenshotPath, status: stepStatus });
+              this.recordRunEvent(userId, runId, 'tool_failed', {
+                toolName,
+                status: stepStatus,
+                error: toolErrorMessage,
+                durationMs: Date.now() - stepStartedAt,
+                resultPreview: summarizeForLog(toolResult),
+              }, { agentId, stepId });
               console.warn(
                 `[Run ${shortenRunId(runId)}] step=${stepIndex} failed tool=${toolName} durationMs=${Date.now() - stepStartedAt} error=${summarizeForLog(toolErrorMessage, 160)}`
               );
             } else {
               this.emit(userId, 'run:tool_end', { runId, stepId, toolName, result: toolResult, screenshotPath, status: stepStatus });
+              this.recordRunEvent(userId, runId, 'tool_completed', {
+                toolName,
+                status: stepStatus,
+                durationMs: Date.now() - stepStartedAt,
+                resultPreview: summarizeForLog(toolResult),
+              }, { agentId, stepId });
               console.info(
                 `[Run ${shortenRunId(runId)}] step=${stepIndex} done tool=${toolName} status=${stepStatus} durationMs=${Date.now() - stepStartedAt} result=${summarizeForLog(toolResult)}`
               );
@@ -2013,25 +2245,49 @@ class AgentEngine {
             db.prepare('UPDATE agent_steps SET status = ?, error = ?, completed_at = datetime(\'now\') WHERE id = ?')
               .run('failed', err.message, stepId);
             this.emit(userId, 'run:tool_end', { runId, stepId, toolName, error: err.message, status: 'failed' });
+            this.recordRunEvent(userId, runId, 'tool_failed', {
+              toolName,
+              status: 'failed',
+              error: err.message,
+              durationMs: Date.now() - stepStartedAt,
+            }, { agentId, stepId });
             console.warn(
               `[Run ${shortenRunId(runId)}] step=${stepIndex} failed tool=${toolName} durationMs=${Date.now() - stepStartedAt} error=${summarizeForLog(err.message, 160)}`
             );
           }
 
           const execution = classifyToolExecution(toolName, toolArgs, toolResult, toolErrorMessage);
+          execution.artifacts = await extractArtifactsFromResult(toolName, toolResult);
           toolExecutions.push(execution);
+          if (deliverableWorkflow && Array.isArray(execution.artifacts) && execution.artifacts.length > 0) {
+            for (const artifact of execution.artifacts) {
+              if (!deliverableArtifacts.some((existing) => (
+                (existing.path && artifact.path && existing.path === artifact.path)
+                || (existing.uri && artifact.uri && existing.uri === artifact.uri)
+              ))) {
+                deliverableArtifacts.push(artifact);
+                this.recordRunEvent(userId, runId, 'deliverable_artifact_produced', {
+                  type: deliverableWorkflow.selection.type,
+                  toolName,
+                  artifact,
+                }, { agentId, stepId });
+              }
+            }
+          }
           this.persistRunMetadata(runId, {
             evidenceSources: [...new Set(toolExecutions.map((item) => item.evidenceSource).filter(Boolean))],
             subagentState: this.listSubagents(runId),
+            deliverableArtifacts,
           });
 
+          const toolResultLimits = resolveToolResultLimits(toolName, loopPolicy);
           const toolMessage = {
             role: 'tool',
             name: toolName,
             tool_call_id: toolCall.id,
             content: compactToolResult(toolName, toolArgs, toolResult, {
-              softLimit: toolReplayBudget,
-              hardLimit: 3200
+              softLimit: toolResultLimits.softLimit,
+              hardLimit: toolResultLimits.hardLimit,
             })
           };
           messages.push(toolMessage);
@@ -2050,7 +2306,7 @@ class AgentEngine {
               ].filter(Boolean).join(' ')
             });
 
-            if (consecutiveToolFailures >= MAX_CONSECUTIVE_TOOL_FAILURES) {
+            if (consecutiveToolFailures >= loopPolicy.maxConsecutiveToolFailures) {
               messages.push({
                 role: 'system',
                 content: `There were ${consecutiveToolFailures} consecutive tool failures. Stop calling tools now and return a clear blocker response that summarizes attempted actions and concrete errors.`
@@ -2124,6 +2380,11 @@ class AgentEngine {
         );
         this.activeRuns.delete(runId);
         this.emit(userId, 'run:stopped', { runId, triggerSource });
+        this.recordRunEvent(userId, runId, 'run_stopped', {
+          triggerSource,
+          totalTokens,
+          iterations: iteration,
+        }, { agentId });
         return { runId, content: '', totalTokens, iterations: iteration, status: 'stopped' };
       }
 
@@ -2237,6 +2498,46 @@ class AgentEngine {
         });
       }
 
+      if (deliverableWorkflow && deliverablePlan) {
+        this.recordRunEvent(userId, runId, 'deliverable_validation_started', {
+          type: deliverableWorkflow.selection.type,
+          artifactCount: deliverableArtifacts.length,
+        }, { agentId });
+        const validationResult = await validateDeliverableExecution({
+          workflow: deliverableWorkflow.workflow,
+          request: deliverableWorkflow.request,
+          plan: deliverablePlan,
+          finalReply: finalResponseText,
+          artifacts: deliverableArtifacts,
+          toolExecutions,
+          runId,
+        });
+        deliverableValidation = validationResult.validation;
+        this.persistRunMetadata(runId, {
+          deliverable: validationResult.result,
+        });
+        if (deliverableValidation.status !== 'passed') {
+          this.recordRunEvent(userId, runId, 'deliverable_validation_failed', {
+            type: deliverableWorkflow.selection.type,
+            errors: deliverableValidation.errors,
+            warnings: deliverableValidation.warnings,
+          }, { agentId });
+          throw new DeliverableValidationError(
+            deliverableValidation.summary || `Deliverable validation failed for ${deliverableWorkflow.selection.type}.`,
+            {
+              validation: deliverableValidation,
+              result: validationResult.result,
+            },
+          );
+        }
+        await this.persistDeliverableMemory(userId, runId, agentId, validationResult.result);
+        this.recordRunEvent(userId, runId, 'deliverable_completed', {
+          type: deliverableWorkflow.selection.type,
+          artifactCount: validationResult.result.artifacts.length,
+          summary: validationResult.result.summary,
+        }, { agentId });
+      }
+
       db.prepare('UPDATE agent_runs SET status = ?, total_tokens = ?, final_response = ?, updated_at = datetime(\'now\'), completed_at = datetime(\'now\') WHERE id = ?')
         .run('completed', totalTokens, finalResponseText || null, runId);
 
@@ -2327,6 +2628,26 @@ class AgentEngine {
         executionMode: analysis?.mode || 'execute',
         verificationStatus: verification?.status || 'skipped',
       });
+      this.recordRunEvent(userId, runId, 'run_completed', {
+        contentPreview: String(finalResponseText || lastContent || '').slice(0, 240),
+        totalTokens,
+        iterations: iteration,
+        triggerSource,
+        executionMode: analysis?.mode || 'execute',
+        verificationStatus: verification?.status || 'skipped',
+      }, { agentId });
+
+      // ── on_loop_end hook ──
+      // Fire-and-forget: plugins can use this for self-improvement, memory
+      // consolidation, analytics, or other post-run housekeeping.
+      if (globalHooks.has('on_loop_end')) {
+        globalHooks.run('on_loop_end', {
+          userId, runId, agentId, status: 'completed',
+          iterations: iteration, totalTokens,
+          taskAnalysis: analysis,
+          finalContent: finalResponseText,
+        }).catch(() => {});
+      }
 
       return { runId, content: lastContent, totalTokens, iterations: iteration, status: 'completed' };
     } catch (err) {
@@ -2339,6 +2660,11 @@ class AgentEngine {
         this.cleanupSubagentsForRun(runId, { cancelRunning: true });
         this.activeRuns.delete(runId);
         this.emit(userId, 'run:stopped', { runId, triggerSource });
+        this.recordRunEvent(userId, runId, 'run_stopped', {
+          triggerSource,
+          totalTokens,
+          iterations: iteration,
+        }, { agentId });
         return { runId, content: '', totalTokens, iterations: iteration, status: 'stopped' };
       }
 
@@ -2348,6 +2674,7 @@ class AgentEngine {
         triggerSource === 'messaging'
         && options.source
         && options.chatId
+        && err?.disableAutonomousRetry !== true
         && retryCount < this.getMessagingRetryLimit(maxIterations)
       );
 
@@ -2402,6 +2729,9 @@ class AgentEngine {
         return this.runWithModel(userId, userMessage, retryOptions, _modelOverride);
       }
 
+      const deliverableFailureResponse = err?.deliverableResult?.summary
+        || err?.deliverableValidation?.summary
+        || '';
       let messagingFailureContent = '';
       let sendSucceeded = false;
       if (triggerSource === 'messaging' && options.source && options.chatId) {
@@ -2460,7 +2790,14 @@ class AgentEngine {
       }
 
       db.prepare('UPDATE agent_runs SET status = ?, error = ?, final_response = ?, updated_at = datetime(\'now\') WHERE id = ?')
-        .run('failed', err.message, sendSucceeded ? (messagingFailureContent || null) : null, runId);
+        .run(
+          'failed',
+          err.message,
+          sendSucceeded
+            ? (messagingFailureContent || null)
+            : (deliverableFailureResponse || null),
+          runId,
+        );
       console.error(
         `[Run ${shortenRunId(runId)}] failed trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens} error=${summarizeForLog(err.message, 180)}`
       );
@@ -2468,6 +2805,12 @@ class AgentEngine {
       this.cleanupSubagentsForRun(runId, { cancelRunning: true });
       this.activeRuns.delete(runId);
       this.emit(userId, 'run:error', { runId, error: err.message });
+      this.recordRunEvent(userId, runId, 'run_failed', {
+        error: err.message,
+        totalTokens,
+        iterations: iteration,
+        deliverableType: deliverableWorkflow?.selection?.type || null,
+      }, { agentId });
 
       if (messagingFailureContent) {
         return {
@@ -2488,10 +2831,10 @@ class AgentEngine {
     const childRunId = uuidv4();
     const subEngine = new AgentEngine(this.io, {
       app: options.app || this.app,
-      cliExecutor: this.cliExecutor,
       browserController: this.browserController,
       androidController: this.androidController,
       runtimeManager: this.runtimeManager,
+      workspaceManager: this.workspaceManager,
       messagingManager: this.messagingManager,
       mcpManager: this.mcpManager,
       skillRunner: this.skillRunner,
@@ -2798,7 +3141,9 @@ class AgentEngine {
       runMeta.aborted = true;
       this.emit(runMeta.userId, 'run:stopping', { runId });
       for (const pid of runMeta.toolPids) {
-        this.cliExecutor?.kill(pid, 'aborted');
+        if (this.runtimeManager && typeof this.runtimeManager.killCommand === 'function') {
+          void this.runtimeManager.killCommand(runMeta.userId, pid, 'aborted');
+        }
       }
       runMeta.toolPids.clear();
     }