@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/engine/turn-loop.js

@@ -5,17 +5,20 @@
  * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
  */
 import { initialTurnState, newTurnId } from "./turn-state.js";
+import { formatFriendlyError } from "./friendly-error.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { ContextLimitError } from "../exceptions.js";
 import { logger } from "../logging/logger.js";
 import { checkTokenBudget, createBudgetTracker } from "./token-budget.js";
 import { StreamingToolQueue } from "./streaming-tool-queue.js";
-import { estimateTokens } from "../context/compaction.js";
+import { downgradeImagePayloadsInHistory, estimateTokens, messageHasBase64ImagePayload, } from "../context/compaction.js";
 import { isTruncatedStop } from "../llm/stop-reason.js";
 import { isAbortError } from "../llm/client-base.js";
 import { crossedReactiveThreshold } from "./reactive-threshold.js";
 import { COMPLETE_GOAL_TOOL_NAME } from "../tool-system/builtin/complete-goal.js";
-import { createGoalBudgetTracker, recordGoalUsage, goalBudgetExceeded, } from "./goal.js";
+import { CANCEL_GOAL_TOOL_NAME } from "../tool-system/builtin/cancel-goal.js";
+import { addTokenUsage, cacheHitRateFromUsage, cumulativeCacheHitRate, } from "./session-usage.js";
+import { createGoalBudgetTracker, recordGoalUsage, goalBudgetExceeded, applyGoalExtension, limitProximity, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "./goal.js";
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
  * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
@@ -27,7 +30,7 @@ export function toolResultToBlock(result) {
         tool_use_id: result.id,
         content: result.error
             ? `Error: ${result.error}`
-            : result.contentBlocks ?? (result.result ?? "(no output)"),
+            : (result.contentBlocks ?? result.result ?? "(no output)"),
     };
     if (result.isError || result.error)
         block.is_error = true;
@@ -48,15 +51,113 @@ export class TurnLoop {
     currentTurnLog = logger;
     /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
     lastCtxEmit = -1;
+    currentTurnUsage = {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+    };
+    currentCumulativeUsage;
+    pendingImageMessages = new Set();
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
      * loop forces a stop so a stuck goal can't loop forever.
      */
     stopBlockCount = 0;
-    constructor(deps, config) {
+    /**
+     * Run-scoped goal budget tracker (Goal mode). Hoisted to an instance field
+     * (not a run() local) so extend() can bump its budgets mid-run. Null when no
+     * goal or between runs.
+     */
+    goalTracker = null;
+    /**
+     * Whether an approaching_limit marker was already emitted for the current
+     * ceiling. Reset when the run advances past the moment (a fresh extension, or
+     * the goal completing) so the next approach re-announces. Prevents the marker
+     * being re-emitted every turn while still within the approach threshold.
+     */
+    approachAnnounced = false;
+    /**
+     * Extend the in-flight run's limits (TODO 3.1 — 运行中续轮/加预算). Mutates
+     * the maxTurns ceiling, the maxStopBlocks cap, and/or the live goal budgets;
+     * the loop re-reads all of them each turn so the change takes effect on the
+     * next iteration. No-op for fields not supplied. Returns the resulting
+     * effective limits.
+     */
+    extend(opts) {
+        const elapsedMs = this.goalTracker ? Date.now() - this.goalTracker.startedAtMs : 0;
+        const next = applyGoalExtension(this.config.maxTurns, this.goalTracker?.goal, this.goalTracker?.tokensUsed ?? 0, elapsedMs, opts);
+        this.config = { ...this.config, maxTurns: next.maxTurns };
+        if (this.goalTracker) {
+            // Replace the goal object rather than mutating its fields: the tracker's
+            // goal may be a shared/frozen reference, and goalBudgetExceeded reads
+            // tracker.goal.{tokenBudget,timeBudgetMs} live, so a fresh object with the
+            // new caps takes effect on the next turn either way.
+            this.goalTracker.goal = {
+                ...this.goalTracker.goal,
+                tokenBudget: next.tokenBudget,
+                timeBudgetMs: next.timeBudgetMs,
+            };
+        }
+        // Raise the consecutive-stop-block cap — for a re-blocked goal this is the
+        // limit that actually bites, so an extend that only bumped maxTurns/budgets
+        // couldn't keep it going. Resolve the current cap the same way the loop does.
+        const curCap = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+        const nextCap = typeof opts.addStopBlocks === "number" && opts.addStopBlocks > 0
+            ? curCap + Math.floor(opts.addStopBlocks)
+            : curCap;
+        this.config = { ...this.config, maxStopBlocks: nextCap };
+        // ANY extension resets the consecutive stop-block streak: the user just
+        // asked to keep going, so a goal that was repeatedly re-blocked shouldn't be
+        // immediately re-capped. (Previously only addTurns reset it, leaving a
+        // budget-only extension unable to un-stick a capped goal.)
+        const extended = (opts.addTurns ?? 0) > 0 ||
+            (opts.addStopBlocks ?? 0) > 0 ||
+            (opts.addTokenBudget ?? 0) > 0 ||
+            (opts.addTimeBudgetMs ?? 0) > 0;
+        if (extended) {
+            this.stopBlockCount = 0;
+            // Let the next approach re-announce against the raised ceilings.
+            this.approachAnnounced = false;
+        }
+        return { ...next, maxStopBlocks: nextCap };
+    }
+    /**
+     * Goal mode only: if the run is nearing EITHER stop ceiling (maxTurns or
+     * maxStopBlocks) and we haven't announced it yet, emit one approaching_limit
+     * marker so the UI can offer a "再续" button while the run is still live.
+     * Watches both limits because a re-blocked goal hits the stop-block cap long
+     * before maxTurns. Idempotent within an approach window via approachAnnounced.
+     */
+    maybeAnnounceApproachingLimit() {
+        if (!this.config.goal || this.approachAnnounced)
+            return;
+        const cap = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+        const prox = limitProximity(this.turnCount, this.config.maxTurns, this.stopBlockCount, cap);
+        if (!prox.approaching)
+            return;
+        this.approachAnnounced = true;
+        this.config.onStream?.({
+            type: "goal_progress",
+            status: "approaching_limit",
+            round: this.stopBlockCount,
+            turnsRemaining: prox.turnsRemaining,
+            stopBlocksRemaining: prox.stopBlocksRemaining,
+            nearest: prox.nearest,
+        });
+    }
+    constructor(deps, 
+    // Not readonly: extend() bumps maxTurns mid-run (TODO 3.1), and the
+    // constructor below rewrites onStream. The loop reads config fields fresh
+    // each turn so mutations take effect on the next iteration.
+    config) {
         this.deps = deps;
         this.config = config;
+        for (const msg of this.config.freshImageMessages ?? []) {
+            this.pendingImageMessages.add(msg);
+        }
         // Wrap onStream so a single throwing handler can't silently break
         // the channel for the rest of the run. A 2026-05-25 incident saw a
         // sub-agent's events stop reaching the renderer ~23s into its run —
@@ -95,11 +196,61 @@ export class TurnLoop {
      * `decision` / `stop`. Use this instead of `deps.hooks.emit` directly so
      * every emit carries the same context envelope.
      */
+    /**
+     * Persist a turn_stopped marker on a user Stop so a resume can rebuild the
+     * renderer's "你在 Ns 后停止了" line (the in-memory turn_end is lost on reload,
+     * which makes the interrupted turn fold behind the process-card header).
+     * Skipped for sub-agents — their signal.aborted is usually a parent abort,
+     * not a user Stop, and sub-agent turns aren't shown as interruptible. The
+     * underlying append is idempotent, so calling this at several abort returns
+     * for one Stop still writes a single marker.
+     */
+    markStopped() {
+        if (this.deps.isSubAgent === true)
+            return;
+        this.deps.transcript.appendTurnStopped();
+    }
+    prepareMessagesForModel(messages) {
+        const preserveMessages = this.pendingImageMessages.size > 0 ? this.pendingImageMessages : undefined;
+        const result = downgradeImagePayloadsInHistory(messages, { preserveMessages });
+        if (result.replacedCount > 0) {
+            this.currentTurnLog.info("context.image_payload_downgrade", {
+                cat: "context",
+                images: result.replacedCount,
+                pendingFresh: this.pendingImageMessages.size,
+            });
+        }
+        return result.messages;
+    }
+    markPendingImagesConsumed(messages) {
+        if (this.pendingImageMessages.size === 0)
+            return messages;
+        const consumedMessages = this.pendingImageMessages.size;
+        this.pendingImageMessages.clear();
+        const result = downgradeImagePayloadsInHistory(messages);
+        if (result.replacedCount > 0) {
+            this.currentTurnLog.info("context.image_payload_consumed", {
+                cat: "context",
+                images: result.replacedCount,
+                messages: consumedMessages,
+            });
+        }
+        return result.messages;
+    }
+    trackFreshImageMessage(message) {
+        if (messageHasBase64ImagePayload(message)) {
+            this.pendingImageMessages.add(message);
+        }
+    }
     async emitHook(event, data = {}) {
         return this.deps.hooks.emit(event, {
             ...data,
             isSubAgent: this.deps.isSubAgent === true,
             sessionId: this.deps.sessionId,
+            // The run's abort signal, so handlers that make their own LLM calls
+            // (e.g. the Goal stop-judge) can be cut short when the user hits Stop
+            // mid-call instead of blocking until the sub-call returns.
+            signal: this.config.signal,
         });
     }
     /**
@@ -132,9 +283,14 @@ export class TurnLoop {
         this.lastCtxEmit = ctx;
         this.config.onStream({ type: "usage_update", promptTokens: ctx });
     }
-    emitCtxFromUsage(promptTokens, messages) {
+    recordResponseUsage(usage) {
+        this.currentTurnUsage = addTokenUsage(this.currentTurnUsage, usage);
+        this.currentCumulativeUsage = this.deps.recordCumulativeUsage?.(usage);
+    }
+    emitCtxFromUsage(usage, messages) {
         if (!this.config.onStream)
             return;
+        const promptTokens = usage.promptTokens;
         // Reverse-derive overhead from this authoritative reading so the next
         // estimate-based emit (post-tool-result) is calibrated.
         const msgsEstimate = estimateTokens(messages);
@@ -147,10 +303,47 @@ export class TurnLoop {
             derivedOverhead: overhead,
             prev: this.lastCtxEmit,
         });
-        if (promptTokens === this.lastCtxEmit)
+        const promptChanged = promptTokens !== this.lastCtxEmit;
+        if (promptChanged)
+            this.lastCtxEmit = promptTokens;
+        // Forward the provider's cache counts so the UI can show a hit rate. Only
+        // attach fields the provider actually reported — a spread keeps them off
+        // the event entirely when undefined, so the renderer can tell "no cache
+        // info this turn" from "0 cached". Estimate-path emits don't call this and
+        // so carry no cache fields (correct: an estimate has no cache reading).
+        const singleTurnCacheHitRate = cacheHitRateFromUsage(this.currentTurnUsage);
+        const cumulative = this.currentCumulativeUsage;
+        const cumulativeHitRate = cumulative ? cumulativeCacheHitRate(cumulative) : undefined;
+        if (!promptChanged && singleTurnCacheHitRate === undefined && cumulativeHitRate === undefined) {
             return;
-        this.lastCtxEmit = promptTokens;
-        this.config.onStream({ type: "usage_update", promptTokens });
+        }
+        this.config.onStream({
+            type: "usage_update",
+            promptTokens,
+            ...(usage.cacheReadTokens !== undefined ? { cacheReadTokens: usage.cacheReadTokens } : {}),
+            ...(usage.cacheCreationTokens !== undefined
+                ? { cacheCreationTokens: usage.cacheCreationTokens }
+                : {}),
+            singleTurnPromptTokens: this.currentTurnUsage.promptTokens,
+            singleTurnCacheReadTokens: this.currentTurnUsage.cacheReadTokens ?? 0,
+            singleTurnCacheCreationTokens: this.currentTurnUsage.cacheCreationTokens ?? 0,
+            ...(singleTurnCacheHitRate !== undefined ? { singleTurnCacheHitRate } : {}),
+            ...(cumulative
+                ? {
+                    cumulativePromptTokens: cumulative.cumulativePromptTokens,
+                    cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                    ...(cumulativeHitRate !== undefined
+                        ? { cumulativeCacheHitRate: cumulativeHitRate }
+                        : {}),
+                    // Legacy aliases for existing renderer builds. New UI code reads the
+                    // cumulative* fields above.
+                    sessionPromptTokens: cumulative.cumulativePromptTokens,
+                    sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                    sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                }
+                : {}),
+        });
     }
     /**
      * Run the multi-turn agent loop until completion.
@@ -163,9 +356,12 @@ export class TurnLoop {
         // wall-clock start now and accumulates prompt+completion tokens across
         // every turn; the guardrail below force-stops the run once any configured
         // budget is blown — the unattended-safety backstop.
-        const goalTracker = this.config.goal
+        this.goalTracker = this.config.goal
             ? createGoalBudgetTracker(this.config.goal, Date.now())
             : null;
+        const goalTracker = this.goalTracker;
+        // Fresh run: re-arm the approaching-limit announcement.
+        this.approachAnnounced = false;
         // run() must never reject: the engine's post-run bookkeeping (saveState
         // with the terminal reason, on_session_end hook) runs AFTER this call and
         // outside the engine's try, so a throw here would leave the session
@@ -176,6 +372,13 @@ export class TurnLoop {
         try {
             while (this.turnCount < this.config.maxTurns) {
                 this.turnCount++;
+                this.currentTurnUsage = {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheCreationTokens: 0,
+                };
                 // Abort fast-path: bail at the loop TOP before doing any per-turn work.
                 // Without this, an aborted child (parent abort, or the 30min per-call
                 // registry timeout) would run a full contextManager.manageAsync (itself
@@ -187,8 +390,15 @@ export class TurnLoop {
                 // boundary between turns. (Mirrors Claude Code's query.ts, where the
                 // aborted check short-circuits before re-entering the streaming loop.)
                 if (this.config.signal?.aborted) {
+                    this.markStopped();
                     return { text: finalText, reason: "aborted_streaming", messages };
                 }
+                // Step-gap steering: messages the host queued via Engine.enqueueSteer
+                // while the previous step was running. Splice them in as user messages so
+                // they join THIS step's request — no abort, no lost in-flight work. Same
+                // loop-top user-push pattern as turnStartInjection / turn-limit warnings
+                // below. Push to transcript too so they persist + survive resume.
+                this.consumeQueuedSteer(messages, "normal_step");
                 const state = initialTurnState(this.turnCount);
                 // Per-turn correlation ID. Every log written through `tlog` (or any
                 // child derived from it) is stamped with `turn` + `turnId`, so
@@ -211,7 +421,10 @@ export class TurnLoop {
                 if (turnStartInjection) {
                     messages.push(turnStartInjection);
                 }
-                // Approaching max turns: inject a warning so the model can wrap up
+                // Approaching max turns: inject a warning so the model can wrap up.
+                // (Model-facing only — the user-facing "再续" marker is handled by
+                // maybeAnnounceApproachingLimit below, which also watches the stop-block
+                // cap, the limit a re-blocked goal actually hits first.)
                 const turnsRemaining = this.config.maxTurns - this.turnCount;
                 if (turnsRemaining === 2) {
                     messages.push({
@@ -220,6 +433,13 @@ export class TurnLoop {
                             "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
                     });
                 }
+                else if (turnsRemaining === 1) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Warning: you have only 1 turn remaining before the turn limit is reached. " +
+                            "Wrap up your work now — your next turn will be your last.</system-reminder>",
+                    });
+                }
                 else if (turnsRemaining === 0) {
                     messages.push({
                         role: "user",
@@ -227,13 +447,21 @@ export class TurnLoop {
                             "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
                     });
                 }
-                // Pre-check: context management (async — may trigger LLM summarization)
+                // Goal mode: announce once when nearing EITHER stop ceiling (turns or
+                // stop-blocks) so the UI can offer a "再续" button while still live.
+                this.maybeAnnounceApproachingLimit();
+                // Pre-check: downgrade image payloads that have already had their one
+                // model-consumption turn, then run context management. Fresh images in
+                // pendingImageMessages are preserved through this next model request.
+                messages = this.prepareMessagesForModel(messages);
+                // Context management (async — may trigger LLM summarization)
                 messages = await this.deps.contextManager.manageAsync(messages);
                 // manageAsync can itself issue an LLM summarization call lasting several
                 // seconds; if the signal aborted during it, stop here rather than
                 // proceeding into the (expensive) main model call. Belt to the loop-top
                 // brace: this catches an abort that landed *inside* context management.
                 if (this.config.signal?.aborted) {
+                    this.markStopped();
                     return { text: finalText, reason: "aborted_streaming", messages };
                 }
                 // No pre-llm ctx emit here: the messages-only estimate would be ~16k
@@ -284,7 +512,7 @@ export class TurnLoop {
                             }
                             catch (retryErr) {
                                 if (!(retryErr instanceof ContextLimitError)) {
-                                    this.config.onStream?.({ type: "error", error: retryErr.message });
+                                    this.config.onStream?.({ type: "error", error: formatFriendlyError(retryErr) });
                                     return { text: finalText, reason: "model_error", messages };
                                 }
                             }
@@ -298,15 +526,28 @@ export class TurnLoop {
                             return { text: finalText, reason: "prompt_too_long", messages };
                         }
                     }
+                    else if (isAbortError(err) || this.config.signal?.aborted) {
+                        // User pressed Stop: the in-flight model call rejected with an
+                        // AbortError. This is NOT a failure — the UI already shows the
+                        // "你在 Ns 后停止了" line, so emitting an error event would stack a
+                        // spurious red "Error:" block on top of an intentional stop.
+                        // Persist a turn_stopped marker so a resume can rebuild that line
+                        // (the renderer's turn_end is in-memory only; without this the
+                        // interrupted turn folds behind the process-card header on reload).
+                        this.patchOrphanedToolUses(messages);
+                        this.markStopped();
+                        return { text: finalText, reason: "aborted_streaming", messages };
+                    }
                     else {
                         this.patchOrphanedToolUses(messages);
-                        this.config.onStream?.({ type: "error", error: err.message });
+                        this.config.onStream?.({ type: "error", error: formatFriendlyError(err) });
                         return { text: finalText, reason: "model_error", messages };
                     }
                 }
-                // UI ctx bar: prefer the provider's authoritative promptTokens.
+                // Record the response once into current-turn and whole-session counters.
                 if (response.usage?.promptTokens !== undefined) {
-                    this.emitCtxFromUsage(response.usage.promptTokens, messages);
+                    this.recordResponseUsage(response.usage);
+                    this.emitCtxFromUsage(response.usage, messages);
                 }
                 // Feed actual token usage back to the context manager so subsequent
                 // compaction decisions use hybrid (actual + delta) estimation rather than
@@ -314,6 +555,7 @@ export class TurnLoop {
                 if (response.usage?.promptTokens !== undefined) {
                     this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
                 }
+                messages = this.markPendingImagesConsumed(messages);
                 // Truncation that cut off a TOOL CALL: the model overflowed
                 // max_output_tokens mid tool-call, so the arg JSON is incomplete (e.g. a
                 // Write whose `content` was clipped, leaving file_path unset). Executing
@@ -342,6 +584,7 @@ export class TurnLoop {
                     response.toolCalls.length === 0 &&
                     response.text) {
                     let combinedText = response.text;
+                    let continuedResponse = false;
                     for (let retry = 0; retry < 3; retry++) {
                         // Don't fire another continuation call if the user cancelled — without
                         // this an abort during a truncated response could still issue up to 3
@@ -358,7 +601,11 @@ export class TurnLoop {
                             },
                         ];
                         try {
-                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
+                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(contMessages), this.deps.tools, this.config.onStream, this.config.signal);
+                            if (contResponse.usage?.promptTokens !== undefined) {
+                                this.recordResponseUsage(contResponse.usage);
+                                continuedResponse = true;
+                            }
                             combinedText += contResponse.text;
                             if (!isTruncatedStop(contResponse.stopReason) || contResponse.toolCalls.length > 0) {
                                 response = { ...contResponse, text: combinedText };
@@ -370,10 +617,9 @@ export class TurnLoop {
                         }
                     }
                     response = { ...response, text: combinedText };
-                }
-                // After any continuation, send latest usage so ctx bar reflects real context
-                if (response.usage?.promptTokens !== undefined) {
-                    this.emitCtxFromUsage(response.usage.promptTokens, messages);
+                    if (continuedResponse && response.usage?.promptTokens !== undefined) {
+                        this.emitCtxFromUsage(response.usage, messages);
+                    }
                 }
                 // Goal-mode run-scoped accounting: add this turn's total token usage
                 // (prompt + completion) to the running total. Done after continuation so
@@ -384,6 +630,7 @@ export class TurnLoop {
                 }
                 // Aborted?
                 if (this.config.signal?.aborted) {
+                    this.markStopped();
                     return { text: finalText, reason: "aborted_streaming", messages };
                 }
                 // Accumulate text
@@ -422,12 +669,15 @@ export class TurnLoop {
                         hasToolUse: false,
                     });
                     messages.push({ role: "assistant", content: finalText });
+                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
                     // on_stop seam: the model wants to stop. Give handlers (Goal mode)
                     // a chance to BLOCK termination and keep the agent working. A
                     // handler returning continueSession=true injects its messages and
                     // we run another turn instead of returning. Bounded by
                     // maxStopBlocks (consecutive) and the outer maxTurns ceiling.
-                    const maxStopBlocks = this.config.maxStopBlocks ?? 8;
+                    const maxStopBlocks = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
                     const stopHook = await this.emitHook("on_stop", {
                         goal: this.config.goal,
                         finalText,
@@ -447,6 +697,10 @@ export class TurnLoop {
                             round: this.stopBlockCount,
                             gaps: goalVerdict?.gaps || undefined,
                         });
+                        // The streak just grew — we may now be nearing the stop-block cap.
+                        // Announce here (before the next turn's top check) so the "再续"
+                        // button shows up against the limit that's actually about to bite.
+                        this.maybeAnnounceApproachingLimit();
                         const injection = wrapHookMessages(stopHook.messages);
                         if (injection) {
                             messages.push(injection);
@@ -499,11 +753,23 @@ export class TurnLoop {
                         });
                     }
                     this.stopBlockCount = 0;
+                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
                     return { text: finalText, reason: "completed", messages };
                 }
                 // Tool execution phase
-                tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
+                tlog.info("turn.tool_use", {
+                    cat: "turn",
+                    tools: response.toolCalls.map((t) => t.toolName),
+                });
                 const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
+                // Per-turn cap: any calls beyond maxToolCallsPerTurn are NOT executed and
+                // NOT added to the assistant message below, so the model never sees a
+                // result for them. Without a heads-up it assumes all ran (acting on
+                // tool output that never happened). Remember the dropped ones so we can
+                // inject a reminder after the executed batch's results. (B-3)
+                const droppedToolCalls = response.toolCalls.slice(this.config.maxToolCallsPerTurn);
                 // Add assistant message with tool_use blocks to messages
                 const assistantBlocks = [];
                 if (response.text) {
@@ -537,19 +803,53 @@ export class TurnLoop {
                     this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
                     this.config.onStream?.({ type: "tool_result", result });
                 }
-                // Fire-and-forget tool use summary (non-blocking)
+                // Fire-and-forget tool use summary (non-blocking). The whole chain is
+                // best-effort observability — a thrown onStream handler, a failed dynamic
+                // import, or a rejecting summarize must never surface as an unhandled
+                // rejection (Node can treat those as fatal). Swallow at the tail. (B-2)
                 if (this.config.onStream) {
-                    import("./tool-summary.js").then(({ generateToolUseSummary }) => {
+                    void import("./tool-summary.js")
+                        .then(({ generateToolUseSummary }) => {
                         if (!this.deps.model.summarize)
                             return;
-                        generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
+                        return generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
                             if (summary) {
                                 this.config.onStream?.({ type: "tool_summary", summary });
                             }
                         });
+                    })
+                        .catch((err) => {
+                        this.currentTurnLog.warn("tool_summary.dispatch_failed", {
+                            cat: "turn",
+                            error: err.message,
+                        });
+                    });
+                }
+                const toolResultMessage = { role: "user", content: resultBlocks };
+                messages.push(toolResultMessage);
+                this.trackFreshImageMessage(toolResultMessage);
+                // B-3: tell the model which of its requested tool calls were dropped by
+                // the per-turn cap so it can re-issue them, instead of silently assuming
+                // they ran. Appended to the same user message that carries the results.
+                if (droppedToolCalls.length > 0) {
+                    tlog.info("turn.tool_calls_capped", {
+                        cat: "turn",
+                        executed: toolCalls.length,
+                        dropped: droppedToolCalls.length,
+                        cap: this.config.maxToolCallsPerTurn,
+                    });
+                    const droppedNames = droppedToolCalls.map((t) => t.toolName).join(", ");
+                    // Separate user message (not folded into the tool_result blocks) so the
+                    // OpenAI converter — which lifts tool_results into standalone role:tool
+                    // messages — keeps the reminder as a plain user turn after them.
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Only the first ${toolCalls.length} of your ${response.toolCalls.length} ` +
+                            `tool calls ran this turn (per-turn limit is ${this.config.maxToolCallsPerTurn}). ` +
+                            `These were NOT executed and produced no result — do NOT assume they ran: ${droppedNames}. ` +
+                            `Re-issue the ones you still need in the next turn.</system-reminder>`,
                     });
                 }
-                messages.push({ role: "user", content: resultBlocks });
                 // Tool results just pushed; recompute ctx so the bar updates *before*
                 // the next model round-trip — large tool outputs can move it sharply.
                 this.emitCtxFromMessages(messages);
@@ -557,10 +857,33 @@ export class TurnLoop {
                 // it has DECLARED the goal done — short-circuit to "completed" WITHOUT
                 // running the judge hook. The tool's result is already in `messages`
                 // above so the summary lands in the transcript. Reset the stop-block
-                // counter so a prior judge-driven block streak doesn't leak out.
+                // counter so a prior judge-driven block streak doesn't leak out. Also
+                // clear the PERSISTED goal so a later bare send doesn't re-inherit a goal
+                // the model just declared finished (the judge's onMet does this when IT
+                // decides; a self-report must do the same, else the goal outlives its
+                // completion and re-arms every follow-up turn).
                 if (goalTracker && toolCalls.some((tc) => tc.toolName === COMPLETE_GOAL_TOOL_NAME)) {
                     tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
                     this.stopBlockCount = 0;
+                    this.deps.clearPersistedGoal?.();
+                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
+                    return { text: finalText, reason: "completed", messages };
+                }
+                // Goal mode: user-initiated cancellation. cancel_goal is the "strong
+                // intent" escape hatch — honor it ONLY when confirm===true (the guard the
+                // tool advertises). A confirmed cancel stops the run AND clears the
+                // persisted goal so it never re-arms; an unconfirmed call is a no-op here
+                // (the tool's own result string already told the model it was ignored).
+                const confirmedCancel = toolCalls.some((tc) => tc.toolName === CANCEL_GOAL_TOOL_NAME && tc.args?.confirm === true);
+                if (goalTracker && confirmedCancel) {
+                    tlog.info("turn.goal_user_cancelled", { cat: "goal" });
+                    this.stopBlockCount = 0;
+                    this.deps.clearPersistedGoal?.();
+                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
                     return { text: finalText, reason: "completed", messages };
                 }
                 // Token budget check
@@ -577,6 +900,9 @@ export class TurnLoop {
                         message: { role: "assistant", content: finalText },
                     });
                     messages.push({ role: "assistant", content: finalText });
+                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        continue;
+                    }
                     return { text: finalText, reason: "completed", messages };
                 }
                 if (budgetDecision === "nudge") {
@@ -632,12 +958,19 @@ export class TurnLoop {
             // engine's post-run saveState records model_error instead of leaving
             // the session stuck at "active".
             this.patchOrphanedToolUses(messages);
+            // A user-initiated Stop also bubbles here (an AbortError thrown from the
+            // per-turn scaffolding). Treat it as a clean abort, not a model_error —
+            // no error event, so the UI shows only the "你停止了本轮" line.
+            if (isAbortError(err) || this.config.signal?.aborted) {
+                this.markStopped();
+                return { text: finalText, reason: "aborted_streaming", messages };
+            }
             this.currentTurnLog.error("turn.unhandled_error", {
                 cat: "turn",
                 error: err.message,
                 stack: err.stack?.split("\n").slice(0, 4).join("\n"),
             });
-            this.config.onStream?.({ type: "error", error: err.message });
+            this.config.onStream?.({ type: "error", error: formatFriendlyError(err) });
             return { text: finalText, reason: "model_error", messages };
         }
         // Max turns reached — do one final summarization call (no tools)
@@ -646,6 +979,8 @@ export class TurnLoop {
             maxTurns: this.config.maxTurns,
             turnCount: this.turnCount,
         });
+        this.consumeQueuedSteer(messages, "finalize_backfill");
+        messages = this.prepareMessagesForModel(messages);
         messages = this.deps.contextManager.manage(messages);
         messages.push({
             role: "user",
@@ -653,8 +988,9 @@ export class TurnLoop {
         });
         this.emitCtxFromMessages(messages);
         try {
-            const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, messages, [], // No tools available for summary turn
+            const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(messages), [], // No tools available for summary turn
             this.config.onStream, this.config.signal);
+            messages = this.markPendingImagesConsumed(messages);
             if (summaryResponse.text) {
                 finalText = summaryResponse.text;
             }
@@ -719,7 +1055,15 @@ export class TurnLoop {
             // non-streaming call here re-sends the whole request the user just
             // aborted. Propagate so the run unwinds cleanly instead of doing
             // more work after cancellation.
-            if (isAbortError(err))
+            //
+            // Check the run signal too, not only isAbortError(err): when a streaming
+            // request is aborted the error sometimes surfaces as a generic
+            // `Error: Request was aborted.` whose `name` is NOT "AbortError"
+            // (wrapping strips it), so isAbortError misses it and we'd fall back —
+            // re-issuing the cancelled request, which then throws "Aborted before
+            // LLM request" from withRetry and surfaces as a scary error on what was
+            // really just a cancel. The signal is the authoritative cancel source.
+            if (isAbortError(err) || this.config.signal?.aborted)
                 throw err;
             // Streaming might have partially emitted — send tombstone to revoke
             this.config.onStream?.({ type: "tombstone", messageId: `turn_${this.turnCount}` });
@@ -734,51 +1078,85 @@ export class TurnLoop {
     get currentTurn() {
         return this.turnCount;
     }
+    consumeQueuedSteer(messages, source) {
+        const steered = this.deps.consumeSteer?.(source) ?? [];
+        let consumed = false;
+        for (const { id, text, clientMessageId } of steered) {
+            if (!text)
+                continue;
+            if (clientMessageId && this.deps.claimClientMessageId?.(clientMessageId, "steer") === false) {
+                logger.info("steer.submit.duplicate_ignored", {
+                    clientMessageId,
+                    steerId: id,
+                    sessionId: this.deps.sessionId,
+                    source,
+                });
+                continue;
+            }
+            consumed = true;
+            messages.push({ role: "user", content: text });
+            this.deps.transcript.appendMessage("user", text, { steerId: id, clientMessageId });
+            this.config.onStream?.({ type: "steer_injected", text, id });
+        }
+        return consumed;
+    }
     /**
      * Generate synthetic error tool_results for any dangling tool_use blocks
      * that never received results (e.g. because the API call failed).
      * Prevents model confusion on the next turn.
      */
     patchOrphanedToolUses(messages) {
-        // Find the last assistant message with tool_use blocks
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const msg = messages[i];
-            if (msg.role !== "assistant" || !Array.isArray(msg.content))
+        // Pre-compute every answered tool_use id across the WHOLE array, then scan
+        // forward and patch EVERY assistant message with a gap — not just the most
+        // recent one. The old version scanned backward and returned at the first
+        // all-answered assistant message, so when several earlier turns each left
+        // orphaned tool_uses (multi-turn API failures) only the latest got patched
+        // and the rest stayed unpaired → a 400 on the next call / on resume.
+        const answeredIds = new Set();
+        for (const msg of messages) {
+            if (!Array.isArray(msg.content))
                 continue;
-            const toolUseIds = [];
             for (const block of msg.content) {
-                if (block.type === "tool_use" && block.id)
-                    toolUseIds.push(block.id);
+                if (block.type === "tool_result" && block.tool_use_id) {
+                    answeredIds.add(block.tool_use_id);
+                }
             }
-            if (toolUseIds.length === 0)
+        }
+        let totalPatched = 0;
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg.role !== "assistant" || !Array.isArray(msg.content))
                 continue;
-            // Check if all tool_use IDs have corresponding tool_results
-            const answeredIds = new Set();
-            for (let j = i + 1; j < messages.length; j++) {
-                const rm = messages[j];
-                if (!Array.isArray(rm.content))
-                    continue;
-                for (const block of rm.content) {
-                    if (block.type === "tool_result" && block.tool_use_id) {
-                        answeredIds.add(block.tool_use_id);
-                    }
+            const orphanedIds = [];
+            for (const block of msg.content) {
+                if (block.type === "tool_use" && block.id && !answeredIds.has(block.id)) {
+                    orphanedIds.push(block.id);
                 }
             }
-            const orphanedIds = toolUseIds.filter((id) => !answeredIds.has(id));
             if (orphanedIds.length === 0)
-                return;
-            // Inject synthetic error results
+                continue;
+            // Synthetic error results, spliced in RIGHT AFTER the offending assistant
+            // message (not appended to the end) so each tool_use is paired in place.
+            // is_error must be set: the Anthropic provider only emits is_error when
+            // the flag is present, otherwise the model reads the cancellation as plain
+            // text output and assumes the tool succeeded.
             const errorBlocks = orphanedIds.map((id) => ({
                 type: "tool_result",
                 tool_use_id: id,
                 content: "Error: Tool execution was cancelled because the previous API call failed.",
+                is_error: true,
             }));
-            messages.push({ role: "user", content: errorBlocks });
+            messages.splice(i + 1, 0, { role: "user", content: errorBlocks });
+            for (const id of orphanedIds)
+                answeredIds.add(id);
+            totalPatched += orphanedIds.length;
+            i += 1; // skip the message we just spliced in
+        }
+        if (totalPatched > 0) {
             this.currentTurnLog.warn("turn.patched_orphaned_tool_uses", {
                 cat: "turn",
-                count: orphanedIds.length,
+                count: totalPatched,
             });
-            return; // Only patch the most recent orphaned set
         }
     }
 }