@bubblebrain-ai/bubble 0.0.13 → 0.0.14

package/dist/agent.js

@@ -22,6 +22,8 @@ import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subage
 import { buildSystemPrompt } from "./system-prompt.js";
 import { isOnlyProviderProtocolArtifacts, stripProviderProtocolArtifacts } from "./provider-artifacts.js";
 import { debugReasoningStream, summarizeDebugText } from "./reasoning-debug.js";
+import { stopAutoServersForSession } from "./tools/server-manager.js";
+import { summarizeAgentEventForTrace, summarizeTraceError, summarizeTraceMessage, summarizeTraceToolResult, summarizeTraceValue, traceEvent, } from "./debug-trace.js";
 const MAX_CONSECUTIVE_OVERFLOW_RECOVERIES = 3;
 const RESIDENT_HISTORY_KEEP_RECENT_TURNS = 3;
 const RESIDENT_HISTORY_MESSAGE_LIMIT = 160;
@@ -29,6 +31,12 @@ const RESIDENT_HISTORY_CHAR_SOFT_LIMIT = 256 * 1024;
 const RESIDENT_HISTORY_CHAR_HARD_LIMIT = 512 * 1024;
 const RESIDENT_HISTORY_HEAP_SOFT_LIMIT = 512 * 1024 * 1024;
 const RESIDENT_HISTORY_HEAP_HARD_LIMIT = 768 * 1024 * 1024;
+const MAX_EMPTY_ASSISTANT_RECOVERIES = 1;
+const EMPTY_ASSISTANT_RECOVERY_REMINDER = "The previous model response contained no user-visible assistant content and no tool calls. " +
+    "Respond now with a concise, user-visible answer, or call an available tool if more work is required. " +
+    "Do not put the final answer only in hidden reasoning.";
+const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";
+const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
 export class AgentAbortError extends Error {
     constructor(message = "Agent run cancelled.") {
         super(message);
@@ -237,6 +245,23 @@ export class Agent {
     async *run(userInput, cwd, options = {}) {
         const abortSignal = composeAbortSignals([options.abortSignal, this.budgetLedger?.signal]);
         const inputController = options.inputController;
+        const traceContext = {
+            cwd,
+            sessionFile: this.sessionID,
+            provider: this._providerId || "none",
+            model: this.apiModel || "none",
+        };
+        const emit = (event) => {
+            traceEvent("agent_event", summarizeAgentEventForTrace(event), traceContext);
+            return event;
+        };
+        traceEvent("agent_run_start", {
+            input: summarizeTraceValue(userInput),
+            mode: this._mode,
+            messageCount: this.messages.length,
+            toolCount: this.tools.size,
+            deferredUnlocked: this.unlockedDeferred.size,
+        }, traceContext);
         throwIfAborted(abortSignal);
         const hookBus = new HookBus();
         for (const hooks of createDefaultHooks()) {
@@ -290,7 +315,7 @@ export class Agent {
         };
         if (this._todos.length > 0 && this._todos.every((t) => t.status === "completed")) {
             this.setTodos([]);
-            yield { type: "todos_updated", todos: [] };
+            yield emit({ type: "todos_updated", todos: [] });
         }
         this.appendMessage({ role: "user", content: userInput });
         await hookBus.runBeforeTurn({
@@ -303,350 +328,487 @@ export class Agent {
         });
         flushGovernorReminders();
         let consecutiveOverflowRecoveries = 0;
+        let consecutiveEmptyAssistantRecoveries = 0;
         let step = 0;
-        while (true) {
-            throwIfAborted(abortSignal);
-            flushGovernorReminders();
-            for (const update of this.drainSubagentToolUpdates())
-                yield update;
-            for (const event of applyPendingInputs())
-                yield event;
-            yield { type: "turn_start" };
-            step += 1;
-            hookState.turnCount = step;
-            if (this.taskBudget) {
-                hookState.taskBudget = {
-                    total: this.taskBudget.total,
-                    spent: hookState.taskBudget?.spent ?? 0,
-                };
-            }
-            let forceTextOnlyReason = hookState.forceTextOnlyReason;
-            if (!forceTextOnlyReason && this.maxTurns !== undefined && step >= this.maxTurns) {
-                forceTextOnlyReason = "The configured maximum turns for this agent have been reached.";
-                hookState.forceTextOnlyReason = forceTextOnlyReason;
-            }
-            if (forceTextOnlyReason) {
-                this.injectSystemReminder(buildToolFreezeReminder(forceTextOnlyReason));
-            }
-            const assistantMsg = {
-                role: "assistant",
-                content: "",
-                reasoning: "",
-                toolCalls: [],
-            };
-            const streamingToolCalls = new Map();
-            let turnUsage;
-            let assistantAppended = false;
-            let toolEntries = Array.from(this.tools.values())
-                .filter((t) => !t.deferred || this.unlockedDeferred.has(t.name));
-            const beforeModelCallCtx = {
-                agent: this,
-                cwd,
-                input: userInput,
-                state: hookState,
-                queueReminder,
-                flushReminders: flushGovernorReminders,
-                toolEntries,
-                disableTools: (reason) => {
-                    hookState.forceTextOnlyReason = reason;
-                },
-            };
-            await hookBus.runBeforeModelCall(beforeModelCallCtx);
-            toolEntries = beforeModelCallCtx.toolEntries;
-            if (this._mode !== "plan") {
-                toolEntries = toolEntries.filter((t) => t.name !== "exit_plan_mode");
-            }
-            flushGovernorReminders();
-            const toolDefinitions = ((hookState.forceTextOnlyReason ? [] : toolEntries))
-                .map((t) => ({
-                name: t.name,
-                description: t.description,
-                parameters: t.parameters,
-            }));
-            // LLM-driven compaction runs ahead of projector's algorithmic passes. If
-            // it succeeds, this.messages is replaced with [preserved system+meta] +
-            // [LLM summary] + [last user msg], and the projector becomes a no-op for
-            // budget. If it fails (network error, etc.), the projector's existing
-            // algorithmic fallback still kicks in.
-            await this.maybeCompactWithLLM();
-            try {
-                const projectedMessages = projectMessages(this.messages, {
-                    mode: "budgeted",
+        let autoServersStopped = false;
+        const stopOwnedAutoServers = async () => {
+            if (autoServersStopped)
+                return;
+            autoServersStopped = true;
+            await stopAutoServersForSession(this.sessionID);
+        };
+        let currentAssistantMsg;
+        let currentAssistantAppended = false;
+        try {
+            while (true) {
+                throwIfAborted(abortSignal);
+                flushGovernorReminders();
+                for (const update of this.drainSubagentToolUpdates())
+                    yield emit(update);
+                for (const event of applyPendingInputs())
+                    yield emit(event);
+                yield emit({ type: "turn_start" });
+                step += 1;
+                hookState.turnCount = step;
+                if (this.taskBudget) {
+                    hookState.taskBudget = {
+                        total: this.taskBudget.total,
+                        spent: hookState.taskBudget?.spent ?? 0,
+                    };
+                }
+                let forceTextOnlyReason = hookState.forceTextOnlyReason;
+                if (!forceTextOnlyReason && this.maxTurns !== undefined && step >= this.maxTurns) {
+                    forceTextOnlyReason = "The configured maximum turns for this agent have been reached.";
+                    hookState.forceTextOnlyReason = forceTextOnlyReason;
+                }
+                if (forceTextOnlyReason) {
+                    this.injectSystemReminder(buildToolFreezeReminder(forceTextOnlyReason));
+                }
+                const assistantMsg = {
+                    role: "assistant",
+                    content: "",
+                    reasoning: "",
+                    toolCalls: [],
+                    model: this._model,
                     providerId: this.providerId,
                     modelId: this.apiModel,
-                    usageAnchorTokens: this.lastInputTokens ?? undefined,
-                    anchorMessageCount: this.lastAnchorMessageCount ?? undefined,
-                });
-                const stream = this.provider.streamChat(projectedMessages, {
-                    model: this.apiModel,
-                    tools: toolDefinitions,
-                    temperature: this.temperature,
-                    thinkingLevel: this.thinkingLevel,
-                    abortSignal,
-                });
-                for await (const chunk of stream) {
-                    throwIfAborted(abortSignal);
-                    switch (chunk.type) {
-                        case "text":
-                            assistantMsg.content += chunk.content;
-                            yield { type: "text_delta", content: chunk.content };
-                            break;
-                        case "reasoning_delta":
-                            debugReasoningStream({
-                                stage: "agent_receive",
-                                providerId: this._providerId,
-                                modelId: this.apiModel,
-                                turnStep: step,
-                                beforeLength: assistantMsg.reasoning?.length ?? 0,
-                                delta: summarizeDebugText(chunk.content),
-                                afterLength: (assistantMsg.reasoning?.length ?? 0) + chunk.content.length,
-                            });
-                            assistantMsg.reasoning = (assistantMsg.reasoning || "") + chunk.content;
-                            yield { type: "reasoning_delta", content: chunk.content };
-                            break;
-                        case "tool_call":
-                            if (chunk.isStart) {
-                                streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
-                                yield { type: "tool_call_start", id: chunk.id, name: chunk.name };
-                            }
-                            if (!streamingToolCalls.has(chunk.id)) {
-                                streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
-                            }
-                            const currentToolCall = streamingToolCalls.get(chunk.id);
-                            if (currentToolCall) {
-                                currentToolCall.name = chunk.name || currentToolCall.name;
-                                currentToolCall.args += chunk.arguments;
-                                if (chunk.argumentsFull !== undefined) {
-                                    currentToolCall.args = chunk.argumentsFull;
+                };
+                const streamingToolCalls = new Map();
+                let turnUsage;
+                let assistantAppended = false;
+                currentAssistantMsg = assistantMsg;
+                currentAssistantAppended = false;
+                let toolEntries = Array.from(this.tools.values())
+                    .filter((t) => !t.deferred || this.unlockedDeferred.has(t.name));
+                const beforeModelCallCtx = {
+                    agent: this,
+                    cwd,
+                    input: userInput,
+                    state: hookState,
+                    queueReminder,
+                    flushReminders: flushGovernorReminders,
+                    toolEntries,
+                    disableTools: (reason) => {
+                        hookState.forceTextOnlyReason = reason;
+                    },
+                };
+                await hookBus.runBeforeModelCall(beforeModelCallCtx);
+                toolEntries = beforeModelCallCtx.toolEntries;
+                if (this._mode !== "plan") {
+                    toolEntries = toolEntries.filter((t) => t.name !== "exit_plan_mode");
+                }
+                flushGovernorReminders();
+                const toolDefinitions = ((hookState.forceTextOnlyReason ? [] : toolEntries))
+                    .map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                }));
+                // LLM-driven compaction runs ahead of projector's algorithmic passes. If
+                // it succeeds, this.messages is replaced with [preserved system+meta] +
+                // [LLM summary] + [last user msg], and the projector becomes a no-op for
+                // budget. If it fails (network error, etc.), the projector's existing
+                // algorithmic fallback still kicks in.
+                await this.maybeCompactWithLLM();
+                try {
+                    const projectedMessages = projectMessages(this.messages, {
+                        mode: "budgeted",
+                        providerId: this.providerId,
+                        modelId: this.apiModel,
+                        usageAnchorTokens: this.lastInputTokens ?? undefined,
+                        anchorMessageCount: this.lastAnchorMessageCount ?? undefined,
+                    });
+                    const providerStartedAt = Date.now();
+                    let streamTextChars = 0;
+                    let streamReasoningChars = 0;
+                    let streamToolCallDeltas = 0;
+                    traceEvent("provider_stream_start", {
+                        residentMessageCount: this.messages.length,
+                        projectedMessageCount: projectedMessages.length,
+                        toolCount: toolDefinitions.length,
+                        thinkingLevel: this.thinkingLevel,
+                        mode: this._mode,
+                    }, traceContext);
+                    const stream = this.provider.streamChat(projectedMessages, {
+                        model: this.apiModel,
+                        tools: toolDefinitions,
+                        temperature: this.temperature,
+                        thinkingLevel: this.thinkingLevel,
+                        abortSignal,
+                    });
+                    for await (const chunk of stream) {
+                        throwIfAborted(abortSignal);
+                        switch (chunk.type) {
+                            case "text":
+                                assistantMsg.content += chunk.content;
+                                streamTextChars += chunk.content.length;
+                                yield emit({ type: "text_delta", content: chunk.content });
+                                break;
+                            case "reasoning_delta":
+                                debugReasoningStream({
+                                    stage: "agent_receive",
+                                    providerId: this._providerId,
+                                    modelId: this.apiModel,
+                                    turnStep: step,
+                                    beforeLength: assistantMsg.reasoning?.length ?? 0,
+                                    delta: summarizeDebugText(chunk.content),
+                                    afterLength: (assistantMsg.reasoning?.length ?? 0) + chunk.content.length,
+                                });
+                                assistantMsg.reasoning = (assistantMsg.reasoning || "") + chunk.content;
+                                streamReasoningChars += chunk.content.length;
+                                yield emit({ type: "reasoning_delta", content: chunk.content });
+                                break;
+                            case "tool_call":
+                                if (chunk.isStart) {
+                                    streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
+                                    yield emit({ type: "tool_call_start", id: chunk.id, name: chunk.name });
+                                }
+                                if (!streamingToolCalls.has(chunk.id)) {
+                                    streamingToolCalls.set(chunk.id, { id: chunk.id, name: chunk.name, args: "" });
                                 }
-                                if (chunk.argumentsCorrupt) {
-                                    currentToolCall.argsCorrupt = true;
+                                const currentToolCall = streamingToolCalls.get(chunk.id);
+                                if (currentToolCall) {
+                                    currentToolCall.name = chunk.name || currentToolCall.name;
+                                    currentToolCall.args += chunk.arguments;
+                                    if (chunk.argumentsFull !== undefined) {
+                                        currentToolCall.args = chunk.argumentsFull;
+                                    }
+                                    if (chunk.argumentsCorrupt) {
+                                        currentToolCall.argsCorrupt = true;
+                                    }
+                                    if (chunk.arguments) {
+                                        streamToolCallDeltas += 1;
+                                        yield emit({
+                                            type: "tool_call_delta",
+                                            id: currentToolCall.id,
+                                            name: currentToolCall.name,
+                                            argumentsDelta: chunk.arguments,
+                                            arguments: currentToolCall.args,
+                                        });
+                                    }
                                 }
-                                if (chunk.arguments) {
-                                    yield {
-                                        type: "tool_call_delta",
+                                if (chunk.isEnd && currentToolCall) {
+                                    assistantMsg.toolCalls.push({
+                                        id: currentToolCall.id,
+                                        name: currentToolCall.name,
+                                        arguments: currentToolCall.args,
+                                        ...(currentToolCall.argsCorrupt ? { argsCorrupt: true } : {}),
+                                    });
+                                    yield emit({
+                                        type: "tool_call_end",
                                         id: currentToolCall.id,
                                         name: currentToolCall.name,
-                                        argumentsDelta: chunk.arguments,
                                         arguments: currentToolCall.args,
-                                    };
+                                    });
+                                    streamingToolCalls.delete(chunk.id);
                                 }
-                            }
-                            if (chunk.isEnd && currentToolCall) {
-                                assistantMsg.toolCalls.push({
-                                    id: currentToolCall.id,
-                                    name: currentToolCall.name,
-                                    arguments: currentToolCall.args,
-                                    ...(currentToolCall.argsCorrupt ? { argsCorrupt: true } : {}),
-                                });
-                                yield {
-                                    type: "tool_call_end",
-                                    id: currentToolCall.id,
-                                    name: currentToolCall.name,
-                                    arguments: currentToolCall.args,
-                                };
-                                streamingToolCalls.delete(chunk.id);
-                            }
-                            break;
-                        case "usage":
-                            turnUsage = chunk.usage;
-                            this.budgetLedger?.recordUsage(chunk.usage, this.budgetSource);
-                            this.lastInputTokens = chunk.usage.promptTokens;
-                            this.lastAnchorMessageCount = this.messages.length;
-                            if (hookState.taskBudget) {
-                                hookState.taskBudget.spent += chunk.usage.promptTokens + chunk.usage.completionTokens;
-                                if (hookState.taskBudget.spent >= hookState.taskBudget.total) {
-                                    hookState.forceTextOnlyReason = "The configured task budget for this agent has been exhausted.";
+                                break;
+                            case "usage":
+                                turnUsage = chunk.usage;
+                                assistantMsg.usage = chunk.usage;
+                                this.budgetLedger?.recordUsage(chunk.usage, this.budgetSource);
+                                this.lastInputTokens = chunk.usage.promptTokens;
+                                this.lastAnchorMessageCount = this.messages.length;
+                                if (hookState.taskBudget) {
+                                    hookState.taskBudget.spent += chunk.usage.promptTokens + chunk.usage.completionTokens;
+                                    if (hookState.taskBudget.spent >= hookState.taskBudget.total) {
+                                        hookState.forceTextOnlyReason = "The configured task budget for this agent has been exhausted.";
+                                    }
                                 }
-                            }
-                            break;
+                                break;
+                        }
+                        for (const update of this.drainSubagentToolUpdates())
+                            yield emit(update);
                     }
-                    for (const update of this.drainSubagentToolUpdates())
-                        yield update;
-                }
-                throwIfAborted(abortSignal);
-                this.appendMessage(assistantMsg);
-                assistantAppended = true;
-            }
-            catch (error) {
-                if (assistantAppended) {
-                    throw error;
-                }
-                if (!isContextOverflowError(error)) {
-                    throw error;
-                }
-                if (consecutiveOverflowRecoveries >= MAX_CONSECUTIVE_OVERFLOW_RECOVERIES) {
-                    throw error;
+                    traceEvent("provider_stream_end", {
+                        elapsedMs: Date.now() - providerStartedAt,
+                        textChars: streamTextChars,
+                        reasoningChars: streamReasoningChars,
+                        toolCallDeltas: streamToolCallDeltas,
+                        toolCalls: assistantMsg.toolCalls?.length ?? 0,
+                        usage: turnUsage,
+                    }, traceContext);
+                    throwIfAborted(abortSignal);
+                    const assistantHasContent = assistantMsg.content.trim().length > 0;
+                    const assistantHasToolCalls = !!assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0;
+                    if (!assistantHasContent && !assistantHasToolCalls) {
+                        if (consecutiveEmptyAssistantRecoveries < MAX_EMPTY_ASSISTANT_RECOVERIES) {
+                            consecutiveEmptyAssistantRecoveries += 1;
+                            this.injectSystemReminder(EMPTY_ASSISTANT_RECOVERY_REMINDER);
+                            yield emit({ type: "turn_end", usage: turnUsage, willContinue: true });
+                            continue;
+                        }
+                        assistantMsg.content = EMPTY_ASSISTANT_FALLBACK;
+                        assistantMsg.reasoning = "";
+                        yield emit({ type: "text_delta", content: assistantMsg.content });
+                    }
+                    this.appendMessage(assistantMsg);
+                    assistantAppended = true;
+                    currentAssistantAppended = true;
                 }
-                const droppedMessages = await this.recoverFromOverflow(consecutiveOverflowRecoveries);
-                consecutiveOverflowRecoveries += 1;
-                yield { type: "context_recovered", droppedMessages, reason: "overflow" };
-                continue;
-            }
-            consecutiveOverflowRecoveries = 0;
-            // Execute tools if any
-            if (assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0) {
-                const parsedCalls = [];
-                for (let index = 0; index < assistantMsg.toolCalls.length; index++) {
-                    const tc = assistantMsg.toolCalls[index];
-                    try {
-                        parsedCalls.push({
-                            ...tc,
-                            parsedArgs: JSON.parse(tc.arguments),
-                            ...(tc.argsCorrupt ? { argsCorrupt: true } : {}),
-                        });
+                catch (error) {
+                    traceEvent("provider_stream_error", {
+                        error: summarizeTraceError(error),
+                    }, traceContext);
+                    if (assistantAppended) {
+                        throw error;
+                    }
+                    if (!isContextOverflowError(error)) {
+                        if (!isAbortLikeError(error, abortSignal) && shouldAppendModelInterruptedBoundary(this.messages)) {
+                            this.appendMessage(createModelInterruptedMessage(error, {
+                                model: this._model,
+                                providerId: this.providerId,
+                                modelId: this.apiModel,
+                            }));
+                            assistantAppended = true;
+                        }
+                        throw error;
                     }
-                    catch {
-                        parsedCalls.push({ ...tc, parsedArgs: {}, argsCorrupt: true });
+                    if (consecutiveOverflowRecoveries >= MAX_CONSECUTIVE_OVERFLOW_RECOVERIES) {
+                        throw error;
                     }
+                    const droppedMessages = await this.recoverFromOverflow(consecutiveOverflowRecoveries);
+                    consecutiveOverflowRecoveries += 1;
+                    yield emit({ type: "context_recovered", droppedMessages, reason: "overflow" });
+                    continue;
                 }
-                const executedResults = [];
-                for (let index = 0; index < parsedCalls.length; index++) {
-                    throwIfAborted(abortSignal);
-                    let tc = parsedCalls[index];
-                    let blockedResult;
-                    await hookBus.runBeforeToolCall({
-                        agent: this,
-                        cwd,
-                        input: userInput,
-                        state: hookState,
-                        queueReminder,
-                        flushReminders: flushGovernorReminders,
-                        toolCall: tc,
-                        blockedResult,
-                        replaceToolCall: (toolCall) => {
-                            tc = toolCall;
-                        },
-                        blockToolCall: (result) => {
-                            blockedResult = result;
-                        },
-                    });
-                    assistantMsg.toolCalls[index] = {
-                        id: tc.id,
-                        name: tc.name,
-                        arguments: tc.arguments,
-                    };
-                    flushGovernorReminders();
-                    yield { type: "tool_start", id: tc.id, name: tc.name, args: tc.parsedArgs };
-                    const todosVersionBefore = this._todosVersion;
-                    const modeVersionBefore = this._modeVersion;
-                    const updateQueue = createUpdateQueue();
-                    let result;
-                    if (blockedResult) {
-                        result = blockedResult;
+                consecutiveOverflowRecoveries = 0;
+                consecutiveEmptyAssistantRecoveries = 0;
+                // Execute tools if any
+                if (assistantMsg.toolCalls && assistantMsg.toolCalls.length > 0) {
+                    const parsedCalls = [];
+                    for (let index = 0; index < assistantMsg.toolCalls.length; index++) {
+                        const tc = assistantMsg.toolCalls[index];
+                        try {
+                            parsedCalls.push({
+                                ...tc,
+                                parsedArgs: JSON.parse(tc.arguments),
+                                ...(tc.argsCorrupt ? { argsCorrupt: true } : {}),
+                            });
+                        }
+                        catch {
+                            parsedCalls.push({ ...tc, parsedArgs: {}, argsCorrupt: true });
+                        }
                     }
-                    else {
-                        const toolExecution = this.executeTool(tc, cwd, abortSignal, (update) => updateQueue.push(update));
-                        let settled = false;
-                        let resolved;
-                        let rejected;
-                        void toolExecution
-                            .then((value) => {
-                            resolved = value;
-                        })
-                            .catch((error) => {
-                            rejected = error;
-                        })
-                            .finally(() => {
-                            settled = true;
-                            updateQueue.wake();
+                    const executedResults = [];
+                    const appendCancelledToolMessages = (startIndex) => {
+                        for (let pendingIndex = startIndex; pendingIndex < parsedCalls.length; pendingIndex++) {
+                            const pending = parsedCalls[pendingIndex];
+                            const pendingResult = cancelledToolResult(pending.name);
+                            this.appendMessage({
+                                role: "tool",
+                                toolCallId: pending.id,
+                                content: pendingResult.content,
+                                metadata: pendingResult.metadata,
+                                isError: pendingResult.isError,
+                            });
+                            executedResults.push(pendingResult);
+                        }
+                    };
+                    for (let index = 0; index < parsedCalls.length; index++) {
+                        if (abortSignal?.aborted) {
+                            appendCancelledToolMessages(index);
+                            throwIfAborted(abortSignal);
+                        }
+                        let tc = parsedCalls[index];
+                        let blockedResult;
+                        await hookBus.runBeforeToolCall({
+                            agent: this,
+                            cwd,
+                            input: userInput,
+                            state: hookState,
+                            queueReminder,
+                            flushReminders: flushGovernorReminders,
+                            toolCall: tc,
+                            blockedResult,
+                            replaceToolCall: (toolCall) => {
+                                tc = toolCall;
+                            },
+                            blockToolCall: (result) => {
+                                blockedResult = result;
+                            },
                         });
-                        while (!settled || updateQueue.hasItems()) {
-                            for (const update of updateQueue.drain()) {
-                                yield { type: "tool_update", id: tc.id, name: tc.name, update };
+                        assistantMsg.toolCalls[index] = {
+                            id: tc.id,
+                            name: tc.name,
+                            arguments: tc.arguments,
+                        };
+                        flushGovernorReminders();
+                        const toolStartedAt = Date.now();
+                        traceEvent("tool_execute_start", {
+                            id: tc.id,
+                            name: tc.name,
+                            args: summarizeTraceValue(tc.parsedArgs),
+                            argsCorrupt: tc.argsCorrupt,
+                        }, traceContext);
+                        yield emit({ type: "tool_start", id: tc.id, name: tc.name, args: tc.parsedArgs });
+                        const todosVersionBefore = this._todosVersion;
+                        const modeVersionBefore = this._modeVersion;
+                        const updateQueue = createUpdateQueue();
+                        let result;
+                        if (blockedResult) {
+                            result = blockedResult;
+                        }
+                        else {
+                            const toolExecution = this.executeTool(tc, cwd, abortSignal, (update) => updateQueue.push(update));
+                            let settled = false;
+                            let cancelledByAbort = false;
+                            let resolved;
+                            let rejected;
+                            void toolExecution
+                                .then((value) => {
+                                resolved = value;
+                            })
+                                .catch((error) => {
+                                rejected = error;
+                            })
+                                .finally(() => {
+                                settled = true;
+                                updateQueue.wake();
+                            });
+                            while (!settled || updateQueue.hasItems()) {
+                                for (const update of updateQueue.drain()) {
+                                    yield emit({ type: "tool_update", id: tc.id, name: tc.name, update });
+                                }
+                                for (const update of this.drainSubagentToolUpdates())
+                                    yield emit(update);
+                                if (!settled) {
+                                    const waitStatus = await updateQueue.wait(abortSignal);
+                                    if (waitStatus === "aborted" && !settled) {
+                                        cancelledByAbort = true;
+                                        break;
+                                    }
+                                }
                             }
-                            for (const update of this.drainSubagentToolUpdates())
-                                yield update;
-                            if (!settled) {
-                                await updateQueue.wait();
+                            if (cancelledByAbort) {
+                                result = cancelledToolResult(tc.name);
                             }
+                            else {
+                                if (rejected)
+                                    throw rejected;
+                                result = resolved ?? { content: `Error: Tool "${tc.name}" returned no result`, isError: true };
+                            }
+                        }
+                        await hookBus.runAfterToolCall({
+                            agent: this,
+                            cwd,
+                            input: userInput,
+                            state: hookState,
+                            queueReminder,
+                            flushReminders: flushGovernorReminders,
+                            toolCall: tc,
+                            result,
+                            replaceResult: (next) => {
+                                result = next;
+                            },
+                        });
+                        // Honor the model's server-declared per-tool-output token cap (e.g.
+                        // gpt-5.5 reports 10000). Without this, 4-5 large file reads in a row
+                        // blow past the input window even though our local estimate looks fine.
+                        const truncatedOutput = truncateToolOutputForModel(result.content, this.providerId, this.apiModel);
+                        traceEvent("tool_execute_end", {
+                            id: tc.id,
+                            name: tc.name,
+                            elapsedMs: Date.now() - toolStartedAt,
+                            result: summarizeTraceToolResult(result),
+                            outputTruncation: {
+                                truncated: truncatedOutput.truncated,
+                                originalTokens: truncatedOutput.originalTokens,
+                                finalTokens: truncatedOutput.finalTokens,
+                                limit: truncatedOutput.limit,
+                            },
+                        }, traceContext);
+                        this.appendMessage({
+                            role: "tool",
+                            toolCallId: tc.id,
+                            content: truncatedOutput.content,
+                            metadata: result.metadata,
+                            isError: result.isError,
+                        });
+                        this.compactResidentHistory();
+                        flushGovernorReminders();
+                        this.onToolResult?.(tc.name, result);
+                        executedResults.push(result);
+                        yield emit({ type: "tool_end", id: tc.id, name: tc.name, result });
+                        for (const update of this.drainSubagentToolUpdates())
+                            yield emit(update);
+                        if (this._todosVersion !== todosVersionBefore) {
+                            yield emit({ type: "todos_updated", todos: this.getTodos() });
+                        }
+                        if (this._modeVersion !== modeVersionBefore) {
+                            yield emit({ type: "mode_changed", mode: this._mode });
+                        }
+                        if (abortSignal?.aborted) {
+                            appendCancelledToolMessages(index + 1);
+                            throwIfAborted(abortSignal);
                         }
-                        if (rejected)
-                            throw rejected;
-                        result = resolved ?? { content: `Error: Tool "${tc.name}" returned no result`, isError: true };
                     }
-                    throwIfAborted(abortSignal);
-                    await hookBus.runAfterToolCall({
+                    await hookBus.runBeforeContinuation({
                         agent: this,
                         cwd,
                         input: userInput,
                         state: hookState,
                         queueReminder,
                         flushReminders: flushGovernorReminders,
-                        toolCall: tc,
-                        result,
-                        replaceResult: (next) => {
-                            result = next;
+                        toolCalls: parsedCalls,
+                        toolResults: executedResults,
+                        requestTextOnlyTurn: (reason) => {
+                            hookState.forceTextOnlyReason = reason;
                         },
                     });
-                    // Honor the model's server-declared per-tool-output token cap (e.g.
-                    // gpt-5.5 reports 10000). Without this, 4-5 large file reads in a row
-                    // blow past the input window even though our local estimate looks fine.
-                    const truncatedOutput = truncateToolOutputForModel(result.content, this.providerId, this.apiModel);
-                    this.appendMessage({
-                        role: "tool",
-                        toolCallId: tc.id,
-                        content: truncatedOutput.content,
-                        metadata: result.metadata,
-                        isError: result.isError,
-                    });
-                    this.compactResidentHistory();
                     flushGovernorReminders();
-                    this.onToolResult?.(tc.name, result);
-                    executedResults.push(result);
-                    yield { type: "tool_end", id: tc.id, name: tc.name, result };
-                    for (const update of this.drainSubagentToolUpdates())
-                        yield update;
-                    if (this._todosVersion !== todosVersionBefore) {
-                        yield { type: "todos_updated", todos: this.getTodos() };
-                    }
-                    if (this._modeVersion !== modeVersionBefore) {
-                        yield { type: "mode_changed", mode: this._mode };
-                    }
+                    yield emit({ type: "turn_end", usage: turnUsage, willContinue: true });
+                    // Auto-continue: if we have tool results, the LLM needs to respond to them.
+                    // Emitting the turn boundary keeps UI renderers aligned with the persisted
+                    // assistant/tool message sequence instead of merging the next answer into
+                    // the tool-call turn.
+                    continue;
                 }
-                await hookBus.runBeforeContinuation({
+                await hookBus.runAfterTurn({
                     agent: this,
                     cwd,
                     input: userInput,
                     state: hookState,
                     queueReminder,
                     flushReminders: flushGovernorReminders,
-                    toolCalls: parsedCalls,
-                    toolResults: executedResults,
-                    requestTextOnlyTurn: (reason) => {
-                        hookState.forceTextOnlyReason = reason;
-                    },
                 });
                 flushGovernorReminders();
-                yield { type: "turn_end", usage: turnUsage, willContinue: true };
-                // Auto-continue: if we have tool results, the LLM needs to respond to them.
-                // Emitting the turn boundary keeps UI renderers aligned with the persisted
-                // assistant/tool message sequence instead of merging the next answer into
-                // the tool-call turn.
-                continue;
+                const willContinue = !!hookState.forceContinuationReason;
+                yield emit({ type: "turn_end", usage: turnUsage, willContinue });
+                if (willContinue) {
+                    delete hookState.forceContinuationReason;
+                    continue;
+                }
+                for (const event of rejectPendingInputs("no_continuation"))
+                    yield emit(event);
+                break;
             }
-            await hookBus.runAfterTurn({
-                agent: this,
-                cwd,
-                input: userInput,
-                state: hookState,
-                queueReminder,
-                flushReminders: flushGovernorReminders,
-            });
-            flushGovernorReminders();
-            const willContinue = !!hookState.forceContinuationReason;
-            yield { type: "turn_end", usage: turnUsage, willContinue };
-            if (willContinue) {
-                delete hookState.forceContinuationReason;
-                continue;
+            for (const update of this.drainSubagentToolUpdates())
+                yield emit(update);
+            await stopOwnedAutoServers();
+            yield emit({ type: "agent_end" });
+        }
+        catch (error) {
+            if (isAbortError(error, abortSignal)) {
+                const appendedBoundary = this.appendInterruptedAssistantBoundary(currentAssistantMsg, currentAssistantAppended);
+                const clearedTodos = this.clearTodosAfterInterruptedRun();
+                traceEvent("agent_run_interrupted", {
+                    appendedBoundary,
+                    clearedTodos,
+                    messageCount: this.messages.length,
+                }, traceContext);
+                if (clearedTodos) {
+                    yield emit({ type: "todos_updated", todos: this.getTodos() });
+                }
             }
-            for (const event of rejectPendingInputs("no_continuation"))
-                yield event;
-            break;
+            throw error;
+        }
+        finally {
+            await stopOwnedAutoServers();
+            traceEvent("agent_run_end", {
+                messageCount: this.messages.length,
+            }, traceContext);
         }
-        for (const update of this.drainSubagentToolUpdates())
-            yield update;
-        yield { type: "agent_end" };
     }
     async recoverFromOverflow(attempt) {
         const before = this.messages.length;
@@ -1274,8 +1436,43 @@ export class Agent {
     }
     appendMessage(message) {
         this.messages.push(message);
+        traceEvent("agent_message_append", {
+            message: summarizeTraceMessage(message),
+            messageCount: this.messages.length,
+        }, {
+            sessionFile: this.sessionID,
+            provider: this._providerId || "none",
+            model: this.apiModel || "none",
+        });
         this.onMessageAppend?.(message);
     }
+    appendInterruptedAssistantBoundary(currentAssistant, currentAssistantAppended) {
+        const last = lastProviderMessage(this.messages);
+        if (last?.role === "assistant" && last.error?.aborted) {
+            return false;
+        }
+        const partialText = !currentAssistantAppended ? currentAssistant?.content.trim() : "";
+        const content = partialText
+            ? `${partialText}\n\n${INTERRUPTED_ASSISTANT_CONTENT}`
+            : INTERRUPTED_ASSISTANT_CONTENT;
+        this.appendMessage({
+            role: "assistant",
+            content,
+            reasoning: !currentAssistantAppended ? currentAssistant?.reasoning : undefined,
+            error: {
+                name: "MessageAbortedError",
+                message: "Assistant response was interrupted by the user.",
+                aborted: true,
+            },
+        });
+        return true;
+    }
+    clearTodosAfterInterruptedRun() {
+        if (this._todos.length === 0)
+            return false;
+        this.setTodos([]);
+        return true;
+    }
     async executeTool(toolCall, cwd, abortSignal, emitUpdate) {
         throwIfAborted(abortSignal);
         if (toolCall.name === "exit_plan_mode" && this._mode !== "plan") {
@@ -1400,9 +1597,61 @@ function throwIfAborted(signal) {
         throw reason;
     throw new AgentAbortError(typeof reason === "string" ? reason : undefined);
 }
+function isAbortLikeError(error, signal) {
+    if (signal?.aborted)
+        return true;
+    if (error instanceof AgentAbortError)
+        return true;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return true;
+    if (typeof error === "object" && error !== null && error.name === "AbortError")
+        return true;
+    return false;
+}
+function isAbortError(error, signal) {
+    return isAbortLikeError(error, signal);
+}
+function shouldAppendModelInterruptedBoundary(messages) {
+    return messages.at(-1)?.role === "tool";
+}
+function createModelInterruptedMessage(error, metadata) {
+    return {
+        role: "assistant",
+        content: `[model request interrupted before a final answer was produced: ${summarizeInterruptError(error)}]`,
+        model: metadata.model,
+        providerId: metadata.providerId,
+        modelId: metadata.modelId,
+    };
+}
+function summarizeInterruptError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : String(error);
+    return message.replace(/\s+/g, " ").trim().slice(0, 240) || "unknown error";
+}
+function lastProviderMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role === "system" || message.role === "meta")
+            continue;
+        return message;
+    }
+    return undefined;
+}
+function cancelledToolResult(toolName) {
+    return {
+        content: `Tool "${toolName}" was cancelled.`,
+        isError: true,
+        status: "cancelled",
+        metadata: { reason: "cancelled" },
+    };
+}
 function createUpdateQueue() {
     const items = [];
     let waiter;
+    let abortCleanup;
     return {
         push(item) {
             items.push(item);
@@ -1414,17 +1663,36 @@ function createUpdateQueue() {
         hasItems() {
             return items.length > 0;
         },
-        wait() {
+        wait(signal) {
             if (items.length > 0)
-                return Promise.resolve();
+                return Promise.resolve("woken");
+            if (signal?.aborted)
+                return Promise.resolve("aborted");
             return new Promise((resolve) => {
+                abortCleanup?.();
+                abortCleanup = undefined;
+                const finish = (status) => {
+                    if (waiter !== resolve)
+                        return;
+                    waiter = undefined;
+                    abortCleanup?.();
+                    abortCleanup = undefined;
+                    resolve(status);
+                };
+                if (signal) {
+                    const onAbort = () => finish("aborted");
+                    signal.addEventListener("abort", onAbort, { once: true });
+                    abortCleanup = () => signal.removeEventListener("abort", onAbort);
+                }
                 waiter = resolve;
             });
         },
         wake() {
             const resolve = waiter;
             waiter = undefined;
-            resolve?.();
+            abortCleanup?.();
+            abortCleanup = undefined;
+            resolve?.("woken");
         },
     };
 }
@@ -1470,21 +1738,26 @@ function sanitizeSubagentSummary(value) {
     return stripProviderProtocolArtifacts(value).trim();
 }
 function needsExplicitFinalSummary(record, executedAnyTool) {
-    // If the subagent actually invoked any tool, always solicit an explicit final
-    // summary. We cannot tell from the stream alone whether a tool-free trailing
-    // turn was the real answer or mid-thought narration ("Let me try X next:").
-    // Asking the model to restate its findings is cheap and yields predictable,
-    // clean output. (Profile-validation notes in `toolNotes` do not count as
-    // actual tool executions.)
-    if (executedAnyTool)
-        return true;
     if (!record.summary)
-        return false;
+        return executedAnyTool;
     if (isOnlyProviderProtocolArtifacts(record.summary))
         return true;
     if (/<\/?[｜|][^<>]*>/.test(record.summary))
         return true;
-    return false;
+    if (!executedAnyTool)
+        return false;
+    if (record.summary === EMPTY_ASSISTANT_FALLBACK)
+        return true;
+    return isLikelyIntermediateSubagentSummary(record.summary);
+}
+function isLikelyIntermediateSubagentSummary(value) {
+    const normalized = value.trim().replace(/\s+/g, " ").toLowerCase();
+    if (!normalized)
+        return false;
+    if (/^(let me|i'll|i will|i need to|i should|i'm going to|now i'll|now i will)\b/.test(normalized)) {
+        return true;
+    }
+    return /:\s*$/.test(normalized) && /\b(read|inspect|check|look|search|try|open)\b/.test(normalized);
 }
 function summarizeSubagentToolEnd(event) {
     const metadata = (event.result.metadata ?? {});