@sschepis/oboto-agent 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -74,7 +74,38 @@ interface ObotoAgentConfig {
     /** as-agent Wasm runtime for slash commands and utilities */
     agentRuntime?: AgentRuntime;
 }
-type AgentEventType = "user_input" | "agent_thought" | "token" | "triage_result" | "tool_execution_start" | "tool_execution_complete" | "tool_round_complete" | "state_updated" | "interruption" | "error" | "cost_update" | "turn_complete" | "permission_denied" | "session_compacted" | "hook_denied" | "hook_message" | "router_event" | "slash_command";
+type AgentEventType = "user_input" | "agent_thought" | "token" | "phase" | "triage_result" | "tool_execution_start" | "tool_execution_complete" | "tool_round_complete" | "state_updated" | "interruption" | "error" | "cost_update" | "turn_complete" | "permission_denied" | "session_compacted" | "hook_denied" | "hook_message" | "router_event" | "slash_command" | "doom_loop" | "heartbeat";
+/** Phase identifiers matching the unified provider's phase system. */
+type AgentPhase = "request" | "precheck" | "planning" | "thinking" | "tools" | "validation" | "memory" | "continuation" | "error" | "doom" | "cancel" | "complete";
+/** Payload for phase events. */
+interface PhaseEvent {
+    phase: AgentPhase;
+    message: string;
+}
+/** Payload for heartbeat events. */
+interface HeartbeatEvent {
+    phase: AgentPhase;
+    elapsedMs: number;
+    message: string;
+}
+/** Payload for doom loop events. */
+interface DoomLoopEvent {
+    reason: string;
+    command: string;
+    count: number;
+    redirected: boolean;
+}
+/** Payload for tool round completion with narrative. */
+interface ToolRoundEvent {
+    iteration: number;
+    tools: Array<{
+        command: string;
+        success: boolean;
+        durationMs?: number;
+    }>;
+    totalToolCalls: number;
+    narrative: string;
+}
 interface AgentEvent<T = unknown> {
     type: AgentEventType;
     payload: T;
@@ -670,6 +701,9 @@ declare class ObotoAgent {
     private usageTracker;
     private usageBridge;
     private routerEventBridge;
+    private heartbeatTimer;
+    private heartbeatStart;
+    private currentPhase;
     constructor(config: ObotoAgentConfig);
     /** Subscribe to agent events. Returns an unsubscribe function. */
     on(type: AgentEventType, handler: EventHandler): () => void;
@@ -731,6 +765,17 @@ declare class ObotoAgent {
      * Returns undefined if RAG is not configured.
      */
     retrieveContext(query: string): Promise<string | undefined>;
+    /** Emit a phase transition event with a human-readable message. */
+    private emitPhase;
+    /** Start a heartbeat that re-emits the current phase every intervalMs. */
+    private startHeartbeat;
+    /** Stop the heartbeat timer. */
+    private stopHeartbeat;
+    /**
+     * Build a human-readable narrative for a batch of tool executions.
+     * E.g. "Just read file data, and ran a command. Sending results back to AI for next steps…"
+     */
+    private buildToolRoundNarrative;
     /**
      * Record a message in the session, context manager, and optionally RAG index.
      * Centralizes message recording to ensure RAG indexing stays in sync.
@@ -1167,4 +1212,4 @@ type TriageInput = {
  */
 declare function createTriageFunction(modelName: string): LScriptFunction<TriageInput, typeof TriageSchema>;
 
-export { AgentDynamicTools, type AgentEvent, AgentEventBus, type AgentEventType, type AgentPipelineConfig, type AgentToolTreeConfig, AgentUsageTracker, ContextManager, ConversationRAG, type ConversationRAGConfig, type DynamicToolEntry, type DynamicToolProvider, type ExecutionOutput, ExecutionSchema, HookIntegration, ObotoAgent, type ObotoAgentConfig, PermissionGuard, type PlanOutput, PlanSchema, type ProviderLike$1 as ProviderLike, type RAGRetrievalResult, RouterEventBridge, SessionCompactor, SlashCommandRegistry, type SummaryOutput, SummarySchema, type ToolExecutionEvent, type TriagePipelineOutput, TriagePipelineSchema, type TriageResult, TriageSchema, type UnifiedCostSummary, UsageBridge, asTokenUsageToLmscript, createAgentToolTree, createAnalyzeRespondPipeline, createEmptySession, createExecutionStep, createFullPipeline, createPlanStep, createRouterTool, createSummaryStep, createToolAuditMiddleware, createToolTimeoutMiddleware, createToolTimingMiddleware, createTriageFunction, createTriagePlanExecutePipeline, createTriageStep, estimateCostFromAsAgent, fromChat, isLLMRouter, lmscriptToAsTokenUsage, runAgentPipeline, sessionToHistory, toChat, toLmscriptProvider };
+export { AgentDynamicTools, type AgentEvent, AgentEventBus, type AgentEventType, type AgentPhase, type AgentPipelineConfig, type AgentToolTreeConfig, AgentUsageTracker, ContextManager, ConversationRAG, type ConversationRAGConfig, type DoomLoopEvent, type DynamicToolEntry, type DynamicToolProvider, type ExecutionOutput, ExecutionSchema, type HeartbeatEvent, HookIntegration, ObotoAgent, type ObotoAgentConfig, PermissionGuard, type PhaseEvent, type PlanOutput, PlanSchema, type ProviderLike$1 as ProviderLike, type RAGRetrievalResult, RouterEventBridge, SessionCompactor, SlashCommandRegistry, type SummaryOutput, SummarySchema, type ToolExecutionEvent, type ToolRoundEvent, type TriagePipelineOutput, TriagePipelineSchema, type TriageResult, TriageSchema, type UnifiedCostSummary, UsageBridge, asTokenUsageToLmscript, createAgentToolTree, createAnalyzeRespondPipeline, createEmptySession, createExecutionStep, createFullPipeline, createPlanStep, createRouterTool, createSummaryStep, createToolAuditMiddleware, createToolTimeoutMiddleware, createToolTimingMiddleware, createTriageFunction, createTriagePlanExecutePipeline, createTriageStep, estimateCostFromAsAgent, fromChat, isLLMRouter, lmscriptToAsTokenUsage, runAgentPipeline, sessionToHistory, toChat, toLmscriptProvider };

package/dist/index.js

@@ -1163,6 +1163,9 @@ var ObotoAgent = class {
   usageTracker;
   usageBridge;
   routerEventBridge;
+  heartbeatTimer = null;
+  heartbeatStart = 0;
+  currentPhase = "request";
   constructor(config) {
     this.config = config;
     this.localProvider = config.localModel;
@@ -1413,6 +1416,75 @@ var ObotoAgent = class {
     const { context } = await this.conversationRAG.retrieve(query);
     return context || void 0;
   }
+  // ── Conversational helpers ──────────────────────────────────────────
+  /** Emit a phase transition event with a human-readable message. */
+  emitPhase(phase, message) {
+    this.currentPhase = phase;
+    this.bus.emit("phase", { phase, message });
+  }
+  /** Start a heartbeat that re-emits the current phase every intervalMs. */
+  startHeartbeat(phase, intervalMs = 3e3) {
+    this.stopHeartbeat();
+    this.heartbeatStart = Date.now();
+    this.currentPhase = phase;
+    this.heartbeatTimer = setInterval(() => {
+      const elapsed = Date.now() - this.heartbeatStart;
+      const secs = Math.round(elapsed / 1e3);
+      const message = phase === "thinking" ? `Waiting for AI response\u2026 (${secs}s)` : `${phase}\u2026 (${secs}s)`;
+      this.bus.emit("heartbeat", { phase: this.currentPhase, elapsedMs: elapsed, message });
+    }, intervalMs);
+  }
+  /** Stop the heartbeat timer. */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  /**
+   * Build a human-readable narrative for a batch of tool executions.
+   * E.g. "Just read file data, and ran a command. Sending results back to AI for next steps…"
+   */
+  buildToolRoundNarrative(tools) {
+    if (tools.length === 0) return "No tools executed.";
+    const verbs = /* @__PURE__ */ new Map();
+    for (const t of tools) {
+      const cmd = t.command.toLowerCase();
+      let verb;
+      if (cmd.includes("read") || cmd.includes("cat") || cmd.includes("get")) {
+        verb = "read file data";
+      } else if (cmd.includes("write") || cmd.includes("edit") || cmd.includes("patch")) {
+        verb = "edited files";
+      } else if (cmd.includes("search") || cmd.includes("grep") || cmd.includes("find") || cmd.includes("glob")) {
+        verb = "searched for information";
+      } else if (cmd.includes("run") || cmd.includes("exec") || cmd.includes("bash") || cmd.includes("shell")) {
+        verb = "ran a command";
+      } else if (cmd.includes("browse") || cmd.includes("web") || cmd.includes("fetch")) {
+        verb = "browsed the web";
+      } else {
+        verb = `used ${t.command}`;
+      }
+      if (!verbs.has(verb)) verbs.set(verb, []);
+      verbs.get(verb).push(t.command);
+    }
+    const parts = Array.from(verbs.keys());
+    let narrative;
+    if (parts.length === 1) {
+      narrative = `Just ${parts[0]}.`;
+    } else if (parts.length === 2) {
+      narrative = `Just ${parts[0]}, and ${parts[1]}.`;
+    } else {
+      const last = parts.pop();
+      narrative = `Just ${parts.join(", ")}, and ${last}.`;
+    }
+    const errors = tools.filter((t) => !t.success);
+    if (errors.length > 0) {
+      const errNames = errors.map((e) => e.command).join(", ");
+      narrative += ` (${errors.length} error${errors.length > 1 ? "s" : ""}: ${errNames})`;
+    }
+    narrative += " Sending results back to AI for next steps\u2026";
+    return narrative;
+  }
   // ── Internal ───────────────────────────────────────────────────────
   /**
    * Record a message in the session, context manager, and optionally RAG index.
@@ -1438,6 +1510,7 @@ var ObotoAgent = class {
     }
   }
   async executionLoop(userInput) {
+    this.emitPhase("request", `Processing: ${userInput.substring(0, 80)}${userInput.length > 80 ? "\u2026" : ""}`);
     this.bus.emit("user_input", { text: userInput });
     const userMsg = {
       role: MessageRole4.User,
@@ -1445,6 +1518,7 @@ var ObotoAgent = class {
     };
     await this.recordMessage(userMsg);
     this.bus.emit("state_updated", { reason: "user_input" });
+    this.emitPhase("planning", "Building context and preparing tools\u2026");
     if (this.conversationRAG) {
       try {
         const { context } = await this.conversationRAG.retrieve(userInput);
@@ -1453,16 +1527,24 @@ var ObotoAgent = class {
             role: "system",
             content: context
           });
+          this.bus.emit("agent_thought", {
+            text: "Retrieved relevant past context via RAG.",
+            model: "system"
+          });
         }
       } catch (err) {
         console.warn("[ObotoAgent] RAG retrieval failed:", err instanceof Error ? err.message : err);
       }
     }
+    this.emitPhase("precheck", "Checking if direct answer is possible\u2026");
+    this.startHeartbeat("precheck");
     const triageResult = await this.triage(userInput);
+    this.stopHeartbeat();
     this.bus.emit("triage_result", triageResult);
     if (this.interrupted) return;
     if (!triageResult.escalate && triageResult.directResponse) {
       const response = triageResult.directResponse;
+      this.emitPhase("complete", "Answered directly \u2014 no tools needed.");
       this.bus.emit("agent_thought", { text: response, model: "local" });
       const assistantMsg = {
         role: MessageRole4.Assistant,
@@ -1474,15 +1556,17 @@ var ObotoAgent = class {
       return;
     }
     if (triageResult.escalate) {
+      this.emitPhase("thinking", `Escalating to remote model: ${triageResult.reasoning}`);
       this.bus.emit("agent_thought", {
         text: triageResult.reasoning,
         model: "local",
         escalating: true
       });
+    } else {
+      this.emitPhase("thinking", "This requires tools and deeper reasoning \u2014 entering agent loop.");
     }
     const modelName = triageResult.escalate ? this.config.remoteModelName : this.config.localModelName;
     const runtime = triageResult.escalate ? this.remoteRuntime : this.localRuntime;
-    console.log("[ObotoAgent] Executing with model:", modelName, "| via lmscript AgentLoop");
     if (this.onToken) {
       await this.executeWithStreaming(runtime, modelName, userInput);
     } else {
@@ -1515,6 +1599,8 @@ var ObotoAgent = class {
    */
   async executeWithAgentLoop(runtime, modelName, userInput) {
     const { z: z5 } = await import("zod");
+    this.emitPhase("thinking", `Turn 1/${this.maxIterations}: Analyzing request\u2026`);
+    this.startHeartbeat("thinking");
     const agentFn = {
       name: "agent-task",
       model: modelName,
@@ -1537,44 +1623,79 @@ user: ${input}` : input;
       temperature: 0.7,
       maxRetries: 1
     };
+    let iterationTools = [];
+    let totalToolCalls = 0;
     const agentConfig = {
       maxIterations: this.maxIterations,
       onToolCall: (tc) => {
         const command = typeof tc.arguments === "object" && tc.arguments !== null ? tc.arguments.command ?? tc.name : tc.name;
         const kwargs = typeof tc.arguments === "object" && tc.arguments !== null ? tc.arguments.kwargs ?? {} : {};
-        this.bus.emit("tool_execution_complete", {
-          command,
-          kwargs,
-          result: typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result)
-        });
         const resultStr = typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result);
+        const isError = resultStr.startsWith("Error:");
+        this.emitPhase("tools", `Running tool: ${String(command)}`);
+        this.bus.emit("tool_execution_start", { command, kwargs });
+        this.bus.emit("tool_execution_complete", { command, kwargs, result: resultStr });
+        iterationTools.push({ command: String(command), success: !isError });
+        totalToolCalls++;
         this.recordToolResult(String(command), kwargs, resultStr);
       },
       onIteration: (iteration, response) => {
-        this.bus.emit("agent_thought", {
-          text: response,
-          model: modelName,
-          iteration
-        });
+        this.stopHeartbeat();
+        if (iterationTools.length > 0) {
+          const narrative = this.buildToolRoundNarrative(iterationTools);
+          const roundEvent = {
+            iteration,
+            tools: iterationTools,
+            totalToolCalls,
+            narrative
+          };
+          this.bus.emit("tool_round_complete", roundEvent);
+          iterationTools = [];
+        }
+        if (response) {
+          this.bus.emit("agent_thought", {
+            text: response,
+            model: modelName,
+            iteration
+          });
+        }
+        this.emitPhase("thinking", `Turn ${iteration + 1}/${this.maxIterations}: Analyzing results\u2026`);
+        this.startHeartbeat("thinking");
         if (this.interrupted) return false;
       }
     };
     const agentLoop = new AgentLoop(runtime, agentConfig);
-    const result = await agentLoop.run(agentFn, userInput);
-    const responseText = result.data.response;
-    const assistantMsg = {
-      role: MessageRole4.Assistant,
-      blocks: [{ kind: "text", text: responseText }]
-    };
-    await this.recordMessage(assistantMsg);
-    this.bus.emit("state_updated", { reason: "assistant_response" });
-    this.bus.emit("turn_complete", {
-      model: modelName,
-      escalated: true,
-      iterations: result.iterations,
-      toolCalls: result.toolCalls.length,
-      usage: result.usage
-    });
+    try {
+      const result = await agentLoop.run(agentFn, userInput);
+      this.stopHeartbeat();
+      if (iterationTools.length > 0) {
+        const narrative = this.buildToolRoundNarrative(iterationTools);
+        this.bus.emit("tool_round_complete", {
+          iteration: result.iterations,
+          tools: iterationTools,
+          totalToolCalls,
+          narrative
+        });
+      }
+      this.emitPhase("memory", "Recording interaction\u2026");
+      const responseText = result.data.response;
+      const assistantMsg = {
+        role: MessageRole4.Assistant,
+        blocks: [{ kind: "text", text: responseText }]
+      };
+      await this.recordMessage(assistantMsg);
+      this.bus.emit("state_updated", { reason: "assistant_response" });
+      this.emitPhase("complete", "Response ready.");
+      this.bus.emit("turn_complete", {
+        model: modelName,
+        escalated: true,
+        iterations: result.iterations,
+        toolCalls: result.toolCalls.length,
+        usage: result.usage
+      });
+    } finally {
+      this.stopHeartbeat();
+    }
   }
   /**
    * Execute with streaming token emission.
@@ -1610,6 +1731,8 @@ user: ${input}` : input;
     ];
     let totalToolCalls = 0;
     const callHistory = [];
+    const consecutiveDupes = /* @__PURE__ */ new Map();
+    let doomLoopRedirected = false;
     const turnStartTime = Date.now();
     const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
     const syntheticCtx = {
@@ -1622,13 +1745,22 @@ user: ${input}` : input;
     await this.middleware.runBeforeExecute(syntheticCtx);
     try {
       for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
-        if (this.interrupted) break;
+        if (this.interrupted) {
+          this.emitPhase("cancel", "Interrupted by user.");
+          break;
+        }
+        this.emitPhase(
+          "thinking",
+          `Turn ${iteration}/${this.maxIterations}: ${iteration === 1 ? "Analyzing request\u2026" : "Analyzing results\u2026"}`
+        );
+        this.startHeartbeat("thinking");
         if (this.costTracker && this.budget) {
           this.costTracker.checkBudget(this.budget);
         }
         await this.rateLimiter?.acquire();
         const isLastIteration = iteration === this.maxIterations;
         if (isLastIteration) {
+          this.emitPhase("continuation", "Maximum iterations reached \u2014 synthesizing final response\u2026");
           messages.push({
             role: "user",
             content: "You have used all available tool iterations. Please provide your final response now based on what you have gathered so far. Do not call any more tools."
@@ -1644,13 +1776,15 @@ user: ${input}` : input;
         try {
           response = await this.streamAndAggregate(provider, params);
         } catch (err) {
+          this.stopHeartbeat();
+          this.emitPhase("error", `LLM call failed: ${err instanceof Error ? err.message : String(err)}`);
           await this.middleware.runError(
             syntheticCtx,
             err instanceof Error ? err : new Error(String(err))
           );
-          console.error("[ObotoAgent] LLM call failed:", err instanceof Error ? err.message : err);
           throw err;
         }
+        this.stopHeartbeat();
         const usage = response?.usage;
         if (usage) {
           const promptTokens = usage.prompt_tokens ?? 0;
@@ -1684,12 +1818,21 @@ user: ${input}` : input;
           });
         }
         if (!toolCalls || toolCalls.length === 0) {
+          if (!content) {
+            this.bus.emit("agent_thought", {
+              text: `Empty response from AI \u2014 iteration ${iteration}`,
+              model: "system"
+            });
+            if (iteration < this.maxIterations) continue;
+          }
+          this.emitPhase("memory", "Recording interaction\u2026");
           const assistantMsg = {
             role: MessageRole4.Assistant,
             blocks: [{ kind: "text", text: content }]
           };
           await this.recordMessage(assistantMsg);
           this.bus.emit("state_updated", { reason: "assistant_response" });
+          this.emitPhase("complete", "Response ready.");
           this.bus.emit("turn_complete", {
             model: modelName,
             escalated: true,
@@ -1704,12 +1847,15 @@ user: ${input}` : input;
           });
           return;
         }
+        this.emitPhase("tools", `Executing ${toolCalls.length} tool(s)\u2026`);
         messages.push({
           role: "assistant",
           content: content || null,
           tool_calls: toolCalls
         });
-        for (const tc of toolCalls) {
+        const roundTools = [];
+        for (let ti = 0; ti < toolCalls.length; ti++) {
+          const tc = toolCalls[ti];
           if (this.interrupted) break;
           let args;
           try {
@@ -1728,6 +1874,7 @@ user: ${input}` : input;
                 tool_call_id: tc.id,
                 content: `Permission denied for tool "${command}": ${outcome.reason ?? "denied by policy"}`
               });
+              roundTools.push({ command, success: false });
               totalToolCalls++;
               continue;
             }
@@ -1740,6 +1887,7 @@ user: ${input}` : input;
                 tool_call_id: tc.id,
                 content: `Tool "${command}" blocked by pre-use hook: ${hookResult.messages.join("; ")}`
               });
+              roundTools.push({ command, success: false });
               totalToolCalls++;
               continue;
             }
@@ -1747,16 +1895,77 @@ user: ${input}` : input;
           const callSig = JSON.stringify({ command, kwargs });
           const dupeCount = callHistory.filter((s) => s === callSig).length;
           callHistory.push(callSig);
+          const prevConsec = consecutiveDupes.get(command) ?? 0;
+          consecutiveDupes.set(command, prevConsec + 1);
           if (dupeCount >= 2) {
-            messages.push({
-              role: "tool",
-              tool_call_id: tc.id,
-              content: `You already called "${command}" with these arguments ${dupeCount} time(s). Use the data you already have.`
-            });
+            if (prevConsec >= 3 && !doomLoopRedirected) {
+              doomLoopRedirected = true;
+              this.emitPhase("doom", `Doom loop detected: repeated calls to "${command}"`);
+              this.bus.emit("doom_loop", {
+                reason: `Repeated calls to "${command}"`,
+                command,
+                count: prevConsec + 1,
+                redirected: true
+              });
+              messages.push({
+                role: "tool",
+                tool_call_id: tc.id,
+                content: `STOP: You have been calling "${command}" repeatedly with the same arguments ${prevConsec + 1} times. This is a doom loop. You MUST take a different approach. Summarize what you know so far and either try a completely different strategy or provide your best answer.`
+              });
+            } else if (doomLoopRedirected && prevConsec >= 5) {
+              this.emitPhase("doom", `Persistent doom loop \u2014 terminating.`);
+              this.bus.emit("doom_loop", {
+                reason: `Persistent doom loop on "${command}"`,
+                command,
+                count: prevConsec + 1,
+                redirected: false
+              });
+              roundTools.push({ command, success: false });
+              totalToolCalls++;
+              if (roundTools.length > 0) {
+                const narrative = this.buildToolRoundNarrative(roundTools);
+                this.bus.emit("tool_round_complete", {
+                  iteration,
+                  tools: roundTools,
+                  totalToolCalls,
+                  narrative
+                });
+              }
+              this.emitPhase("continuation", "Synthesizing response after doom loop\u2026");
+              const assistantMsg = {
+                role: MessageRole4.Assistant,
+                blocks: [{ kind: "text", text: content || "I encountered a repeating pattern and am unable to make further progress. Here is what I have so far." }]
+              };
+              await this.recordMessage(assistantMsg);
+              this.bus.emit("state_updated", { reason: "doom_loop" });
+              this.emitPhase("complete", "Response ready.");
+              this.bus.emit("turn_complete", {
+                model: modelName,
+                escalated: true,
+                iterations: iteration,
+                toolCalls: totalToolCalls,
+                usage: totalUsage
+              });
+              await this.middleware.runComplete(syntheticCtx, {
+                data: content || "doom_loop_terminated",
+                raw: content,
+                usage: totalUsage
+              });
+              return;
+            } else {
+              messages.push({
+                role: "tool",
+                tool_call_id: tc.id,
+                content: `You already called "${command}" with these arguments ${dupeCount} time(s). Use the data you already have.`
+              });
+            }
+            roundTools.push({ command, success: false });
             totalToolCalls++;
             continue;
+          } else {
+            consecutiveDupes.set(command, 0);
           }
-          this.bus.emit("tool_execution_start", { command, kwargs });
+          this.bus.emit("tool_execution_start", { command, kwargs, index: ti, total: toolCalls.length });
           let result;
           let isError = false;
           try {
@@ -1772,8 +1981,9 @@ user: ${input}` : input;
           if (this.hookIntegration) {
             this.hookIntegration.runPostToolUse(command, toolInputStr, truncated, isError);
           }
-          this.bus.emit("tool_execution_complete", { command, kwargs, result: truncated });
+          this.bus.emit("tool_execution_complete", { command, kwargs, result: truncated, error: isError ? truncated : void 0 });
           this.recordToolResult(command, kwargs, truncated);
+          roundTools.push({ command, success: !isError });
           totalToolCalls++;
           messages.push({
             role: "tool",
@@ -1781,13 +1991,24 @@ user: ${input}` : input;
             content: truncated
           });
         }
+        if (roundTools.length > 0) {
+          const narrative = this.buildToolRoundNarrative(roundTools);
+          this.bus.emit("tool_round_complete", {
+            iteration,
+            tools: roundTools,
+            totalToolCalls,
+            narrative
+          });
+        }
       }
+      this.emitPhase("continuation", "Maximum iterations reached \u2014 synthesizing response\u2026");
       const fallbackMsg = {
         role: MessageRole4.Assistant,
         blocks: [{ kind: "text", text: "I reached the maximum number of iterations. Here is what I have so far." }]
       };
       await this.recordMessage(fallbackMsg);
       this.bus.emit("state_updated", { reason: "max_iterations" });
+      this.emitPhase("complete", "Response ready.");
       this.bus.emit("turn_complete", {
         model: modelName,
         escalated: true,
@@ -1801,6 +2022,8 @@ user: ${input}` : input;
         usage: totalUsage
       });
     } catch (err) {
+      this.stopHeartbeat();
+      this.emitPhase("error", `Error: ${err instanceof Error ? err.message : String(err)}`);
       if (!(err instanceof Error && err.message.includes("LLM call failed"))) {
         await this.middleware.runError(
           syntheticCtx,
@@ -1808,6 +2031,8 @@ user: ${input}` : input;
         );
       }
       throw err;
+    } finally {
+      this.stopHeartbeat();
     }
   }
   /**