@cjhyy/code-shell-core 0.6.0-rc.1 → 0.6.0-rc.11

package/dist/engine/session-usage.d.ts

@@ -1,5 +1,17 @@
 import type { TokenUsage } from "../types.js";
 import type { LLMUsageTracker } from "../llm/types.js";
+export interface CumulativeUsageCounters {
+    cumulativePromptTokens: number;
+    cumulativeCacheReadTokens: number;
+    cumulativeCacheCreationTokens: number;
+}
+export declare function emptyCumulativeUsageCounters(): CumulativeUsageCounters;
+export declare function normalizeCumulativeUsageCounters(counters: Partial<CumulativeUsageCounters> | undefined, legacyUsage?: TokenUsage): CumulativeUsageCounters;
+export declare function addCumulativeUsage(counters: Partial<CumulativeUsageCounters> | undefined, usage: TokenUsage): CumulativeUsageCounters;
+export declare function addTokenUsage(left: TokenUsage, right: TokenUsage): TokenUsage;
+export declare function cacheHitRateFromTokens(promptTokens: number, cacheReadTokens: number | undefined, cacheCreationTokens: number | undefined): number | undefined;
+export declare function cacheHitRateFromUsage(usage: TokenUsage | undefined): number | undefined;
+export declare function cumulativeCacheHitRate(counters: CumulativeUsageCounters): number | undefined;
 /**
  * Fold one run's cumulative usage onto a session baseline, producing the new
  * session-cumulative TokenUsage.

package/dist/engine/session-usage.js

@@ -1,3 +1,59 @@
+export function emptyCumulativeUsageCounters() {
+    return {
+        cumulativePromptTokens: 0,
+        cumulativeCacheReadTokens: 0,
+        cumulativeCacheCreationTokens: 0,
+    };
+}
+export function normalizeCumulativeUsageCounters(counters, legacyUsage) {
+    return {
+        cumulativePromptTokens: typeof counters?.cumulativePromptTokens === "number"
+            ? counters.cumulativePromptTokens
+            : (legacyUsage?.promptTokens ?? 0),
+        cumulativeCacheReadTokens: typeof counters?.cumulativeCacheReadTokens === "number"
+            ? counters.cumulativeCacheReadTokens
+            : (legacyUsage?.cacheReadTokens ?? 0),
+        cumulativeCacheCreationTokens: typeof counters?.cumulativeCacheCreationTokens === "number"
+            ? counters.cumulativeCacheCreationTokens
+            : (legacyUsage?.cacheCreationTokens ?? 0),
+    };
+}
+export function addCumulativeUsage(counters, usage) {
+    const current = normalizeCumulativeUsageCounters(counters);
+    return {
+        cumulativePromptTokens: current.cumulativePromptTokens + (usage.promptTokens ?? 0),
+        cumulativeCacheReadTokens: current.cumulativeCacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cumulativeCacheCreationTokens: current.cumulativeCacheCreationTokens + (usage.cacheCreationTokens ?? 0),
+    };
+}
+export function addTokenUsage(left, right) {
+    return {
+        promptTokens: left.promptTokens + (right.promptTokens ?? 0),
+        completionTokens: left.completionTokens + (right.completionTokens ?? 0),
+        totalTokens: left.totalTokens + (right.totalTokens ?? 0),
+        cacheReadTokens: (left.cacheReadTokens ?? 0) + (right.cacheReadTokens ?? 0),
+        cacheCreationTokens: (left.cacheCreationTokens ?? 0) + (right.cacheCreationTokens ?? 0),
+    };
+}
+export function cacheHitRateFromTokens(promptTokens, cacheReadTokens, cacheCreationTokens) {
+    const read = cacheReadTokens ?? 0;
+    const creation = cacheCreationTokens ?? 0;
+    if (read === 0 && creation === 0)
+        return undefined;
+    const uncached = Math.max(0, promptTokens - read - creation);
+    const denom = read + creation + uncached;
+    if (denom === 0)
+        return undefined;
+    return read / denom;
+}
+export function cacheHitRateFromUsage(usage) {
+    if (!usage)
+        return undefined;
+    return cacheHitRateFromTokens(usage.promptTokens ?? 0, usage.cacheReadTokens, usage.cacheCreationTokens);
+}
+export function cumulativeCacheHitRate(counters) {
+    return cacheHitRateFromTokens(counters.cumulativePromptTokens, counters.cumulativeCacheReadTokens, counters.cumulativeCacheCreationTokens);
+}
 /**
  * Fold one run's cumulative usage onto a session baseline, producing the new
  * session-cumulative TokenUsage.

package/dist/engine/steer-queue.d.ts

@@ -9,9 +9,10 @@
 export interface SteerItem {
     id: string;
     text: string;
+    clientMessageId?: string;
 }
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string): SteerItem[];
+export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string): SteerItem[];
 /**
  * Take everything currently queued and clear the list. Returns the drained
  * entries (in order) and the now-empty remainder. The turn loop calls this at

package/dist/engine/steer-queue.js

@@ -1,9 +1,9 @@
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export function enqueueSteerItem(list, id, text) {
+export function enqueueSteerItem(list, id, text, clientMessageId) {
     const t = text?.trim();
     if (!id || !t)
         return list;
-    return [...list, { id, text: t }];
+    return [...list, { id, text: t, ...(clientMessageId ? { clientMessageId } : {}) }];
 }
 /**
  * Take everything currently queued and clear the list. Returns the drained

package/dist/engine/turn-loop.d.ts

@@ -4,13 +4,14 @@
  * Following Claude Code's po_() pattern:
  * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
  */
-import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult } from "../types.js";
+import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult, TokenUsage } from "../types.js";
 import type { SteerItem } from "./steer-queue.js";
 import { ModelFacade } from "./model-facade.js";
 import { ToolExecutor } from "../tool-system/executor.js";
 import { ContextManager } from "../context/manager.js";
 import { HookRegistry } from "../hooks/registry.js";
 import { Transcript } from "../session/transcript.js";
+import { type CumulativeUsageCounters } from "./session-usage.js";
 import { type GoalConfig, type GoalExtension } from "./goal.js";
 export interface TurnLoopConfig {
     maxTurns: number;
@@ -18,6 +19,12 @@ export interface TurnLoopConfig {
     tokenBudget?: number;
     onStream?: StreamCallback;
     signal?: AbortSignal;
+    /**
+     * Image-bearing messages added for the current request and not yet consumed
+     * by the model. TurnLoop preserves their base64 for one successful model
+     * response, then downgrades them to placeholders in the working history.
+     */
+    freshImageMessages?: Iterable<Message>;
     /**
      * Fired after each turn boundary is recorded. Lets the engine flush an
      * up-to-date snapshot to state.json mid-run, so a long run doesn't leave
@@ -76,6 +83,11 @@ export interface TurnLoopDeps {
         before: number;
         after: number;
     } | null;
+    /**
+     * Records one LLM response into the session-monotonic cumulative counters.
+     * Returns the updated counters so usage_update can carry both metric scopes.
+     */
+    recordCumulativeUsage?: (usage: TokenUsage) => CumulativeUsageCounters;
     /**
      * Reads/clears any user messages queued for THIS session via the steering
      * channel (Engine.enqueueSteer) while a run is in flight. Consumed at the top
@@ -84,7 +96,13 @@ export interface TurnLoopDeps {
      * Returns [] when nothing is queued. Wired by Engine; absent in standalone
      * tests (turn loop tolerates undefined).
      */
-    consumeSteer?: () => SteerItem[];
+    consumeSteer?: (source?: "normal_step" | "finalize_backfill") => SteerItem[];
+    /**
+     * Execution-level idempotency guard for host-supplied user/steer intents.
+     * Returns false only when a present clientMessageId has already entered this
+     * run or the persisted transcript. Messages without an id bypass this guard.
+     */
+    claimClientMessageId?: (clientMessageId: string, source: "steer") => boolean;
     /**
      * Clear this session's PERSISTED goal (state.activeGoal) and drop the
      * in-flight goal-stop hook, so a user-initiated cancel_goal both stops the
@@ -121,6 +139,9 @@ export declare class TurnLoop {
     private currentTurnLog;
     /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
     private lastCtxEmit;
+    private currentTurnUsage;
+    private currentCumulativeUsage;
+    private readonly pendingImageMessages;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -178,6 +199,9 @@ export declare class TurnLoop {
      * for one Stop still writes a single marker.
      */
     private markStopped;
+    private prepareMessagesForModel;
+    private markPendingImagesConsumed;
+    private trackFreshImageMessage;
     private emitHook;
     /**
      * Emit a usage_update so the UI ctx bar reflects current message-array
@@ -187,6 +211,7 @@ export declare class TurnLoop {
      * promptTokens to override our estimate).
      */
     private emitCtxFromMessages;
+    private recordResponseUsage;
     private emitCtxFromUsage;
     /**
      * Run the multi-turn agent loop until completion.
@@ -198,6 +223,7 @@ export declare class TurnLoop {
      */
     private callModelWithFallback;
     get currentTurn(): number;
+    private consumeQueuedSteer;
     /**
      * Generate synthetic error tool_results for any dangling tool_use blocks
      * that never received results (e.g. because the API call failed).

package/dist/engine/turn-loop.js

@@ -11,12 +11,13 @@ 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 { 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。
@@ -29,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;
@@ -50,6 +51,15 @@ 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
@@ -145,6 +155,9 @@ export class TurnLoop {
     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 —
@@ -197,6 +210,38 @@ export class TurnLoop {
             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,
@@ -238,6 +283,10 @@ export class TurnLoop {
         this.lastCtxEmit = ctx;
         this.config.onStream({ type: "usage_update", promptTokens: ctx });
     }
+    recordResponseUsage(usage) {
+        this.currentTurnUsage = addTokenUsage(this.currentTurnUsage, usage);
+        this.currentCumulativeUsage = this.deps.recordCumulativeUsage?.(usage);
+    }
     emitCtxFromUsage(usage, messages) {
         if (!this.config.onStream)
             return;
@@ -254,23 +303,46 @@ export class TurnLoop {
             derivedOverhead: overhead,
             prev: this.lastCtxEmit,
         });
-        if (promptTokens === this.lastCtxEmit)
-            return;
-        this.lastCtxEmit = promptTokens;
+        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.config.onStream({
             type: "usage_update",
             promptTokens,
-            ...(usage.cacheReadTokens !== undefined
-                ? { cacheReadTokens: usage.cacheReadTokens }
-                : {}),
+            ...(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,
+                }
+                : {}),
         });
     }
     /**
@@ -300,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
@@ -319,14 +398,7 @@ export class TurnLoop {
                 // 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.
-                const steered = this.deps.consumeSteer?.() ?? [];
-                for (const { id, text } of steered) {
-                    if (!text)
-                        continue;
-                    messages.push({ role: "user", content: text });
-                    this.deps.transcript.appendMessage("user", text);
-                    this.config.onStream?.({ type: "steer_injected", text, id });
-                }
+                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
@@ -378,7 +450,11 @@ export class TurnLoop {
                 // 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: context management (async — may trigger LLM summarization)
+                // 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
@@ -468,8 +544,9 @@ export class TurnLoop {
                         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.recordResponseUsage(response.usage);
                     this.emitCtxFromUsage(response.usage, messages);
                 }
                 // Feed actual token usage back to the context manager so subsequent
@@ -478,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
@@ -506,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
@@ -522,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 };
@@ -534,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, 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
@@ -587,6 +669,9 @@ 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
@@ -668,10 +753,16 @@ 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
@@ -734,7 +825,9 @@ export class TurnLoop {
                         });
                     });
                 }
-                messages.push({ role: "user", content: resultBlocks });
+                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.
@@ -773,6 +866,9 @@ export class TurnLoop {
                     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
@@ -785,6 +881,9 @@ export class TurnLoop {
                     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
@@ -801,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") {
@@ -877,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",
@@ -884,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;
             }
@@ -973,6 +1078,28 @@ 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).

package/dist/git/utils.d.ts

@@ -14,6 +14,18 @@ export interface GitStatusEntry {
 }
 export type { GitLogEntry };
 export declare function isGitRepo(cwd: string): boolean;
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export declare function resolveProjectRoot(cwd: string): string;
 export declare function getCurrentBranch(cwd: string): string;
 export declare function getGitStatus(cwd: string): GitStatusEntry[];
 export declare function getGitDiff(cwd: string, opts?: {

package/dist/git/utils.js

@@ -8,15 +8,15 @@
  * into the string form.
  */
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { parseGitLog } from "./parse-log.js";
-import { resolveExecutable } from "../utils/exec.js";
+import { resolveExecutable, resolveGit } from "../utils/exec.js";
 // Resolve git/gh through PATH×PATHEXT on Windows so a .cmd/.exe shim is found
 // (bare execFile doesn't walk PATHEXT). No-op on POSIX. See utils/exec.ts.
-const GIT_BIN = resolveExecutable("git");
 const GH_BIN = resolveExecutable("gh");
 /** Run git with an argv array and return its trimmed stdout. */
 function git(cwd, args, timeoutMs = 10000) {
-    return execFileSync(GIT_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+    return execFileSync(resolveGit(), args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
 }
 /** Run gh with an argv array and return its trimmed stdout. */
 function gh(cwd, args, timeoutMs = 10000) {
@@ -31,6 +31,33 @@ export function isGitRepo(cwd) {
         return false;
     }
 }
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export function resolveProjectRoot(cwd) {
+    let realCwd = cwd;
+    try {
+        realCwd = realpathSync(cwd);
+    }
+    catch {
+        // Non-existent paths are allowed to fall back unchanged below.
+    }
+    try {
+        const top = git(realCwd, ["rev-parse", "--show-toplevel"], 5000);
+        return top ? realpathSync(top) : realCwd;
+    }
+    catch {
+        return realCwd;
+    }
+}
 export function getCurrentBranch(cwd) {
     return git(cwd, ["branch", "--show-current"], 5000);
 }
@@ -82,13 +109,13 @@ export function gitAdd(cwd, files = ["."]) {
     // `--` ensures a path starting with `-` cannot be parsed as a flag.
     // Each file is its own argv token, so spaces / quotes / non-ASCII pass
     // through verbatim with no shell parsing.
-    execFileSync(GIT_BIN, ["add", "--", ...files], { cwd, timeout: 10000 });
+    execFileSync(resolveGit(), ["add", "--", ...files], { cwd, timeout: 10000 });
 }
 export function gitCommit(cwd, message) {
     // Pre-fix this used `JSON.stringify(message)` which only happened to be
     // safe because JSON.stringify covers most shell metacharacters — but it's
     // not real escaping. The argv form is.
-    return execFileSync(GIT_BIN, ["commit", "-m", message], {
+    return execFileSync(resolveGit(), ["commit", "-m", message], {
         cwd,
         encoding: "utf-8",
         timeout: 30000,
@@ -115,7 +142,7 @@ export function gitCheckout(cwd, branch, create = false) {
         throw new Error(`refusing branch name that starts with '-': ${branch}`);
     }
     const args = create ? ["checkout", "-b", branch] : ["checkout", branch];
-    execFileSync(GIT_BIN, args, { cwd, timeout: 10000 });
+    execFileSync(resolveGit(), args, { cwd, timeout: 10000 });
 }
 export function ghAvailable() {
     try {