@dreb/coding-agent 2.71.0 → 2.73.0

package/dist/core/agent-session.js

@@ -15,7 +15,7 @@
 import { copyFileSync, existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-import { isContextOverflow, isOutputLimitExhaustion, modelsAreEqual, resetApiProviders, supportsMax, supportsXhigh, } from "@dreb/ai";
+import { clampThinkingLevel, getAvailableThinkingLevels, isContextOverflow, isOutputLimitExhaustion, modelsAreEqual, resetApiProviders, } from "@dreb/ai";
 import { getDocsPath, getSubagentSessionsDir } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { sleep } from "../utils/sleep.js";
@@ -41,7 +41,7 @@ import { DEFAULT_BG_PARENT_TURN_LIMIT, DEFAULT_MAX_CONCURRENT_SUBAGENTS, } from
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { resolveThinkingDisplay } from "./thinking.js";
-import { createAllToolDefinitions, createSubagentConcurrencyGate, discoverAgentTypes, getRunningBackgroundAgents, } from "./tools/index.js";
+import { createAllToolDefinitions, createSubagentConcurrencyGate, discoverAgentTypes, formatAgentOutputBlock, getRunningBackgroundAgents, } from "./tools/index.js";
 import { expandSkillContent } from "./tools/skill.js";
 import { createToolDefinitionFromAgentTool, wrapToolDefinition } from "./tools/tool-definition-wrapper.js";
 // ============================================================================
@@ -67,12 +67,6 @@ export function parseSkillBlock(text) {
 // ============================================================================
 // Constants
 // ============================================================================
-/** Standard thinking levels */
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
-/** Thinking levels including xhigh (for supported models). */
-const THINKING_LEVELS_WITH_XHIGH = ["off", "minimal", "low", "medium", "high", "xhigh"];
-/** Complete ordered scale, including the native max tier for supported models. */
-const THINKING_LEVELS_WITH_MAX = [...THINKING_LEVELS_WITH_XHIGH, "max"];
 const MIN_PERFORMANCE_DURATION_MS = 10;
 // ============================================================================
 // AgentSession Class
@@ -90,6 +84,11 @@ export class AgentSession {
     _unsubscribeAgent;
     _eventListeners = [];
     _agentEventQueue = Promise.resolve();
+    /**
+     * Agent events queued on `_agentEventQueue` that haven't finished processing yet.
+     * Persistence happens there, so the session log lags agent state until this is 0.
+     */
+    _agentEventsInFlight = 0;
     /** Tracks pending steering messages for UI display. Removed when delivered. */
     _steeringMessages = [];
     /** Tracks pending follow-up messages for UI display. Removed when delivered. */
@@ -114,6 +113,14 @@ export class AgentSession {
     // Bash execution state
     _bashAbortController = undefined;
     _pendingBashMessages = [];
+    /**
+     * Background-agent cancellation notices that arrived while the parent was busy (see
+     * `_canDeliverCancellationNotices`). Appending them then could land a user message
+     * between an assistant tool call and its result, or ahead of messages not yet persisted.
+     * They are held until the parent is idle again, or are persisted to their session before
+     * it is replaced.
+     */
+    _pendingCancellationNotices = [];
     // Extension system
     _extensionRunner = undefined;
     _turnIndex = 0;
@@ -652,11 +659,19 @@ export class AgentSession {
         if (cancelled) {
             parts.push("This agent was cancelled by the user.");
         }
-        if (!cancelled && (result.exitCode !== 0 || result.errorMessage)) {
+        const failed = !cancelled && (result.exitCode !== 0 || !!result.errorMessage);
+        if (failed) {
             parts.push(`Error: ${result.errorMessage || "unknown"}`);
         }
+        if (result.notes && result.notes.length > 0) {
+            parts.push(...result.notes);
+        }
         if (result.output) {
-            parts.push(result.output);
+            // The agent's own words are delimited from the system lines around them. A chain's
+            // output is already a per-step report with each step's output delimited
+            // (formatSingleResult), so it is not wrapped again.
+            const isChain = result.steps !== undefined;
+            parts.push(isChain ? result.output : formatAgentOutputBlock(result.output, cancelled || failed));
         }
         if (result.sessionFile) {
             parts.push(`Session log: ${result.sessionFile}`);
@@ -680,13 +695,15 @@ export class AgentSession {
             timestamp: Date.now(),
         };
         if (cancelled) {
-            // Cancelled by user (Esc) — add to context and render in chat,
-            // but do NOT trigger a response (the user hit Esc to stop, not to ask a question)
+            // Cancelled by the user (single-agent stop, Esc, or the parent stop) — add to
+            // context and render in chat, but do NOT trigger a response: the user chose to
+            // stop this work, and waking the parent could relaunch it behind their back.
+            // While the parent is busy (streaming, still persisting the run, retrying, or
+            // compacting) the notice is deferred, so it can never split an assistant tool call
+            // from its result.
+            this._pendingCancellationNotices.push(message);
             try {
-                this.agent.appendMessage(message);
-                this.sessionManager.appendMessage(message);
-                this._emit({ type: "message_start", message });
-                this._emit({ type: "message_end", message });
+                this._flushPendingCancellationNotices();
             }
             catch (err) {
                 log.warn(`[subagent] Failed to deliver cancellation message for agent ${agentId}: ${err instanceof Error ? err.message : String(err)}`);
@@ -702,6 +719,8 @@ export class AgentSession {
                 this.agent.steer(message);
             }
             else {
+                // Earlier deferred cancellation notices precede this completion in context.
+                this._flushPendingCancellationNotices();
                 // Fallback: if streaming started between the isStreaming check and this call, deliver as follow-up
                 this.agent.prompt(message).catch((promptErr) => {
                     log.warn(`[subagent] prompt() failed for background agent ${agentId}: ${promptErr instanceof Error ? promptErr.message : String(promptErr)}`);
@@ -720,7 +739,8 @@ export class AgentSession {
                 type: "background_agent_end",
                 agentId,
                 agentType: result.agent,
-                success: result.exitCode === 0,
+                success: !cancelled && result.exitCode === 0,
+                cancelled,
                 model: result.model,
                 thinking: result.thinking,
                 steps: result.steps,
@@ -750,6 +770,7 @@ export class AgentSession {
         // _processAgentEvent, slow earlier queued events can delay agent_end processing
         // and waitForRetry() can miss the in-flight retry.
         this._createRetryPromiseForAgentEnd(event);
+        this._agentEventsInFlight++;
         this._agentEventQueue = this._agentEventQueue.then(() => this._processAgentEvent(event), () => {
             // Prior event failed — already warned by the .catch() below.
             // Swallow the old rejection and continue with the current event.
@@ -853,101 +874,119 @@ export class AgentSession {
         return undefined;
     }
     async _processAgentEvent(event) {
-        // When a user message starts, check if it's from either queue and remove it BEFORE emitting
-        // This ensures the UI sees the updated queue state
-        if (event.type === "message_start" && event.message.role === "user") {
-            this._overflowRecoveryAttempted = false;
-            const messageText = this._getUserMessageText(event.message);
-            if (messageText) {
-                // Check steering queue first
-                const steeringIndex = this._steeringMessages.findIndex((message) => message.text === messageText);
-                if (steeringIndex !== -1) {
-                    this._steeringMessages.splice(steeringIndex, 1);
-                }
-                else {
-                    // Check follow-up queue
-                    const followUpIndex = this._followUpMessages.findIndex((message) => message.text === messageText);
-                    if (followUpIndex !== -1) {
-                        this._followUpMessages.splice(followUpIndex, 1);
+        // The finally runs inline: an extra async wrapper here would add microtask hops to every
+        // queued event and delay event delivery relative to prompt() resolution.
+        try {
+            // When a user message starts, check if it's from either queue and remove it BEFORE emitting
+            // This ensures the UI sees the updated queue state
+            if (event.type === "message_start" && event.message.role === "user") {
+                this._overflowRecoveryAttempted = false;
+                const messageText = this._getUserMessageText(event.message);
+                if (messageText) {
+                    // Check steering queue first
+                    const steeringIndex = this._steeringMessages.findIndex((message) => message.text === messageText);
+                    if (steeringIndex !== -1) {
+                        this._steeringMessages.splice(steeringIndex, 1);
+                    }
+                    else {
+                        // Check follow-up queue
+                        const followUpIndex = this._followUpMessages.findIndex((message) => message.text === messageText);
+                        if (followUpIndex !== -1) {
+                            this._followUpMessages.splice(followUpIndex, 1);
+                        }
                     }
                 }
             }
-        }
-        // Emit to extensions first
-        await this._emitExtensionEvent(event);
-        // Notify all listeners
-        this._emit(event);
-        // Keep a small, mode-independent rolling context for the headless arbiter.
-        if (event.type === "message_end") {
-            this._dispatchArbiter.onMessageEnd(event.message);
-        }
-        else if (event.type === "tool_execution_end") {
-            this._dispatchArbiter.onToolEnd({
-                toolName: event.toolName,
-                isError: event.isError,
-                result: event.result,
-            });
-        }
-        // Handle session persistence
-        if (event.type === "message_end") {
-            // Check if this is a custom message from extensions
-            if (event.message.role === "custom") {
-                // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
-            }
-            else if (event.message.role === "user" ||
-                event.message.role === "assistant" ||
-                event.message.role === "toolResult") {
-                // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
-            }
-            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track assistant message for auto-compaction (checked on agent_end)
-            if (event.message.role === "assistant") {
-                this._lastAssistantMessage = event.message;
-                const assistantMsg = event.message;
-                if (assistantMsg.stopReason !== "error") {
-                    this._overflowRecoveryAttempted = false;
+            // Emit to extensions first
+            await this._emitExtensionEvent(event);
+            // Notify all listeners
+            this._emit(event);
+            // Keep a small, mode-independent rolling context for the headless arbiter.
+            if (event.type === "message_end") {
+                this._dispatchArbiter.onMessageEnd(event.message);
+            }
+            else if (event.type === "tool_execution_end") {
+                this._dispatchArbiter.onToolEnd({
+                    toolName: event.toolName,
+                    isError: event.isError,
+                    result: event.result,
+                });
+            }
+            // Handle session persistence
+            if (event.type === "message_end") {
+                // Check if this is a custom message from extensions
+                if (event.message.role === "custom") {
+                    // Persist as CustomMessageEntry
+                    this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
                 }
-                // Reset retry counter immediately on successful assistant response
-                // This prevents accumulation across multiple LLM calls within a turn
-                if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
-                    this._emit({
-                        type: "auto_retry_end",
-                        success: true,
-                        attempt: this._retryAttempt,
-                    });
-                    this._retryAttempt = 0;
+                else if (event.message.role === "user" ||
+                    event.message.role === "assistant" ||
+                    event.message.role === "toolResult") {
+                    // Regular LLM message - persist as SessionMessageEntry
+                    this.sessionManager.appendMessage(event.message);
                 }
-                const durationMs = assistantMsg.durationMs ?? 0;
-                if (assistantMsg.stopReason !== "error" &&
-                    assistantMsg.stopReason !== "aborted" &&
-                    assistantMsg.usage.output > 0 &&
-                    durationMs >= MIN_PERFORMANCE_DURATION_MS) {
-                    this.performanceTracker.record({
-                        timestamp: new Date().toISOString(),
-                        sessionId: this.sessionId,
-                        provider: assistantMsg.provider,
-                        modelId: assistantMsg.model,
-                        outputTokens: assistantMsg.usage.output,
-                        durationMs,
-                        tps: (assistantMsg.usage.output * 1000) / durationMs,
-                    });
+                // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+                // Track assistant message for auto-compaction (checked on agent_end)
+                if (event.message.role === "assistant") {
+                    this._lastAssistantMessage = event.message;
+                    const assistantMsg = event.message;
+                    if (assistantMsg.stopReason !== "error") {
+                        this._overflowRecoveryAttempted = false;
+                    }
+                    // Reset retry counter immediately on successful assistant response
+                    // This prevents accumulation across multiple LLM calls within a turn
+                    if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
+                        this._emit({
+                            type: "auto_retry_end",
+                            success: true,
+                            attempt: this._retryAttempt,
+                        });
+                        this._retryAttempt = 0;
+                    }
+                    const durationMs = assistantMsg.durationMs ?? 0;
+                    if (assistantMsg.stopReason !== "error" &&
+                        assistantMsg.stopReason !== "aborted" &&
+                        assistantMsg.usage.output > 0 &&
+                        durationMs >= MIN_PERFORMANCE_DURATION_MS) {
+                        this.performanceTracker.record({
+                            timestamp: new Date().toISOString(),
+                            sessionId: this.sessionId,
+                            provider: assistantMsg.provider,
+                            modelId: assistantMsg.model,
+                            outputTokens: assistantMsg.usage.output,
+                            durationMs,
+                            tps: (assistantMsg.usage.output * 1000) / durationMs,
+                        });
+                    }
                 }
             }
-        }
-        // Check auto-retry and auto-compaction after agent completes
-        if (event.type === "agent_end" && this._lastAssistantMessage) {
-            const msg = this._lastAssistantMessage;
-            this._lastAssistantMessage = undefined;
-            // Check for retryable errors first (overloaded, rate limit, server errors)
-            if (this._isRetryableError(msg)) {
-                const didRetry = await this._handleRetryableError(msg);
-                if (didRetry)
-                    return; // Retry was initiated, don't proceed to compaction
+            // Check auto-retry and auto-compaction after agent completes
+            if (event.type === "agent_end") {
+                if (this._lastAssistantMessage) {
+                    const msg = this._lastAssistantMessage;
+                    this._lastAssistantMessage = undefined;
+                    // Check for retryable errors first (overloaded, rate limit, server errors)
+                    if (this._isRetryableError(msg)) {
+                        const didRetry = await this._handleRetryableError(msg);
+                        // Retry was initiated, don't proceed to compaction. Deferred cancellation
+                        // notices stay held while the retry is pending (isRetrying) and are delivered
+                        // after the retried run's agent_end.
+                        if (didRetry)
+                            return;
+                    }
+                    this._resolveRetry();
+                    await this._checkCompaction(msg);
+                }
+                // Deferred cancellation notices are delivered in the finally below once this
+                // agent_end has finished processing (after any retry decision or compaction above).
             }
-            this._resolveRetry();
-            await this._checkCompaction(msg);
+        }
+        finally {
+            this._agentEventsInFlight--;
+            // This event is handled and persisted. If the parent is now idle, deliver cancellation
+            // notices deferred while it was busy. After a run's final agent_end, that places them
+            // after everything the run persisted.
+            this._flushPendingCancellationNotices();
         }
     }
     /** Resolve the pending retry promise */
@@ -1410,8 +1449,9 @@ export class AgentSession {
             }
             return;
         }
-        // Flush any pending bash messages before the new prompt
+        // Flush any pending bash messages and cancellation notices before the new prompt
         this._flushPendingBashMessages();
+        this._flushPendingCancellationNotices();
         // Validate model
         if (!this.model) {
             throw new Error("No model selected.\n\n" +
@@ -1775,6 +1815,7 @@ export class AgentSession {
         }
         this._disconnectFromAgent();
         await this.abort();
+        await this._persistPendingCancellationNoticesBeforeSessionChange();
         this.agent.reset();
         this._dispatchArbiter.clearContext();
         this.sessionManager.newSession({ parentSession: options?.parentSession, cwd: this.cwd });
@@ -1949,14 +1990,16 @@ export class AgentSession {
      * Saves to session and settings only if the level actually changes.
      */
     setThinkingLevel(level) {
-        const availableLevels = this.getAvailableThinkingLevels();
-        const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
+        const effectiveLevel = clampThinkingLevel(this.model, level);
         // Only persist if actually changing
         const isChanging = effectiveLevel !== this.agent.state.thinkingLevel;
         this.agent.setThinkingLevel(effectiveLevel);
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
-            if (this.supportsThinking() || effectiveLevel !== "off") {
+            // A capability clamp (non-reasoning model, `off` on an always-thinking model,
+            // unsupported xhigh/max) must not overwrite the saved preference, so the next
+            // capable model can honor it again.
+            if (this.supportsThinking() && effectiveLevel === level) {
                 this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
             }
         }
@@ -1976,25 +2019,12 @@ export class AgentSession {
         return nextLevel;
     }
     /**
-     * Get available thinking levels for current model.
-     * The provider will clamp to what the specific model supports internally.
+     * Get available thinking levels for current model, in ascending order.
+     * `off` is omitted for models whose thinking cannot be turned off (Claude Opus 5.5+),
+     * and `xhigh` / `max` are included independently per model capability.
      */
     getAvailableThinkingLevels() {
-        if (!this.supportsThinking())
-            return ["off"];
-        if (this.supportsMaxThinking())
-            return THINKING_LEVELS_WITH_MAX;
-        return this.supportsXhighThinking() ? THINKING_LEVELS_WITH_XHIGH : THINKING_LEVELS;
-    }
-    /**
-     * Check if current model supports xhigh thinking level.
-     */
-    supportsXhighThinking() {
-        return this.model ? supportsXhigh(this.model) : false;
-    }
-    /** Check if the current model supports the native max thinking level. */
-    supportsMaxThinking() {
-        return this.model ? supportsMax(this.model) : false;
+        return getAvailableThinkingLevels(this.model);
     }
     /**
      * Check if current model supports thinking/reasoning.
@@ -2006,29 +2036,17 @@ export class AgentSession {
         if (explicitLevel !== undefined) {
             return explicitLevel;
         }
+        const savedLevel = this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
         if (!this.supportsThinking()) {
-            return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+            return savedLevel;
         }
-        return this.thinkingLevel;
-    }
-    _clampThinkingLevel(level, availableLevels) {
-        const ordered = THINKING_LEVELS_WITH_MAX;
-        const available = new Set(availableLevels);
-        const requestedIndex = ordered.indexOf(level);
-        if (requestedIndex === -1) {
-            return availableLevels[0] ?? "off";
-        }
-        for (let i = requestedIndex; i < ordered.length; i++) {
-            const candidate = ordered[i];
-            if (available.has(candidate))
-                return candidate;
-        }
-        for (let i = requestedIndex - 1; i >= 0; i--) {
-            const candidate = ordered[i];
-            if (available.has(candidate))
-                return candidate;
+        // When the current level is only the capability clamp of the saved preference
+        // (e.g. saved `off` shown as `minimal` on Opus 5.5), carry the saved preference
+        // to the next model instead of the clamped value.
+        if (clampThinkingLevel(this.model, savedLevel) === this.thinkingLevel) {
+            return savedLevel;
         }
-        return availableLevels[0] ?? "off";
+        return this.thinkingLevel;
     }
     // =========================================================================
     // Queue Mode Management
@@ -2148,6 +2166,9 @@ export class AgentSession {
         finally {
             this._compactionAbortController = undefined;
             this._reconnectToAgent();
+            // Cancellation notices that arrived while compacting were held back; deliver them
+            // now that the compacted context is in place.
+            this._flushPendingCancellationNotices();
         }
     }
     /**
@@ -3146,6 +3167,60 @@ export class AgentSession {
     get hasPendingBashMessages() {
         return this._pendingBashMessages.length > 0;
     }
+    /**
+     * Whether deferred cancellation notices can be appended now without landing inside
+     * work that is still changing the transcript. Not while the agent streams, while
+     * earlier agent events are still being processed or persisted (the session log would
+     * get the notice ahead of them), while an auto-retry is pending (its backoff or the
+     * retried run), or while compaction or branch summarization runs.
+     */
+    _canDeliverCancellationNotices() {
+        return !this.agent.state.isStreaming && this._agentEventsInFlight === 0 && !this.isRetrying && !this.isCompacting;
+    }
+    /**
+     * Append deferred background-agent cancellation notices to agent state and the session
+     * log, in arrival order, and render them, if the parent is idle (see
+     * `_canDeliverCancellationNotices`). Otherwise they stay queued. They are retried after
+     * each processed agent event (`_processAgentEvent`), before the next prompt, and after manual compaction or
+     * branch navigation. Never triggers a response.
+     */
+    _flushPendingCancellationNotices() {
+        if (this._pendingCancellationNotices.length === 0 || !this._canDeliverCancellationNotices())
+            return;
+        this._appendPendingCancellationNotices();
+    }
+    _appendPendingCancellationNotices() {
+        while (this._pendingCancellationNotices.length > 0) {
+            const message = this._pendingCancellationNotices.shift();
+            this.agent.appendMessage(message);
+            this.sessionManager.appendMessage(message);
+            this._emit({ type: "message_start", message });
+            this._emit({ type: "message_end", message });
+        }
+    }
+    /**
+     * Persist cancellation notices still deferred for the current session before it is replaced
+     * (new session, resume/switch, fork). The run they wait on will never end in this
+     * session, so they are written now instead of being dropped. First every event that session
+     * already produced is processed, so the notices land after the last message it persisted.
+     *
+     * Callers that abort the run first (new session, switch) get a normal append to agent state
+     * and the log. A fork keeps the run going, so if it is still streaming the notices are only
+     * written to the outgoing session's log. Live context is rebuilt from the fork, and must
+     * not get a user message between a tool call and its result.
+     */
+    async _persistPendingCancellationNoticesBeforeSessionChange() {
+        if (this._pendingCancellationNotices.length === 0)
+            return;
+        await this._agentEventQueue.catch(() => undefined);
+        if (this.agent.state.isStreaming) {
+            for (const message of this._pendingCancellationNotices.splice(0)) {
+                this.sessionManager.appendMessage(message);
+            }
+            return;
+        }
+        this._appendPendingCancellationNotices();
+    }
     /**
      * Flush pending bash messages to agent state and session.
      * Called after agent turn completes to maintain proper message ordering.
@@ -3196,6 +3271,7 @@ export class AgentSession {
         }
         this._disconnectFromAgent();
         await this.abort();
+        await this._persistPendingCancellationNoticesBeforeSessionChange();
         this._steeringMessages = [];
         this._followUpMessages = [];
         this._pendingNextTurnMessages = [];
@@ -3229,10 +3305,7 @@ export class AgentSession {
             this.setThinkingLevel(sessionContext.thinkingLevel);
         }
         else {
-            const availableLevels = this.getAvailableThinkingLevels();
-            const effectiveLevel = availableLevels.includes(defaultThinkingLevel)
-                ? defaultThinkingLevel
-                : this._clampThinkingLevel(defaultThinkingLevel, availableLevels);
+            const effectiveLevel = clampThinkingLevel(this.model, defaultThinkingLevel);
             this.agent.setThinkingLevel(effectiveLevel);
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
         }
@@ -3329,6 +3402,8 @@ export class AgentSession {
             }
             skipConversationRestore = result?.skipConversationRestore ?? false;
         }
+        // Cancellation notices belong to the outgoing session: persist them there.
+        await this._persistPendingCancellationNoticesBeforeSessionChange();
         // Clear pending messages (bound to old session state)
         this._pendingNextTurnMessages = [];
         branch(previousSessionFile);
@@ -3540,6 +3615,8 @@ export class AgentSession {
         }
         finally {
             this._branchSummaryAbortController = undefined;
+            // Deliver cancellation notices held back while the branch summary was generated.
+            this._flushPendingCancellationNotices();
         }
     }
     /**