@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.0

package/dist/engine/turn-loop.js

@@ -6,6 +6,7 @@
  */
 import { initialTurnState, newTurnId } from "./turn-state.js";
 import { formatFriendlyError } from "./friendly-error.js";
+import { projectGoalJudgeToolResult, } from "../hooks/goal-stop-hook.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { ContextLimitError } from "../exceptions.js";
 import { logger } from "../logging/logger.js";
@@ -19,7 +20,7 @@ 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 { redactSensitiveToolResultsInMessages, toolResultForDisplay, toolResultTranscriptText, toolResultsForDisplay, } from "../tool-system/tool-result-redaction.js";
 import { addTokenUsage, cacheHitRateFromUsage, cumulativeCacheHitRate, } from "./session-usage.js";
-import { createGoalBudgetTracker, recordGoalUsage, goalBudgetExceeded, applyGoalExtension, limitProximity, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "./goal.js";
+import { createGoalBudgetTracker, recordGoalUsage, goalBudgetTerminationReason, applyGoalExtension, limitProximity, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "./goal.js";
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
  * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
@@ -62,6 +63,7 @@ export class TurnLoop {
     currentCumulativeUsage;
     sensitiveToolResultRedactions = new Map();
     pendingImageMessages = new Set();
+    volatileContextMessages = 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
@@ -160,6 +162,9 @@ export class TurnLoop {
         for (const msg of this.config.freshImageMessages ?? []) {
             this.pendingImageMessages.add(msg);
         }
+        for (const msg of this.config.volatileContextMessages ?? []) {
+            this.volatileContextMessages.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 —
@@ -224,6 +229,23 @@ export class TurnLoop {
         }
         return result.messages;
     }
+    stripVolatileContextMessages(messages) {
+        if (this.volatileContextMessages.size === 0)
+            return messages;
+        let changed = false;
+        const stripped = messages.filter((message) => {
+            const keep = !this.volatileContextMessages.has(message);
+            if (!keep)
+                changed = true;
+            return keep;
+        });
+        return changed ? stripped : messages;
+    }
+    appendVolatileContextMessages(messages) {
+        if (this.volatileContextMessages.size === 0)
+            return messages;
+        return [...this.stripVolatileContextMessages(messages), ...this.volatileContextMessages];
+    }
     markPendingImagesConsumed(messages) {
         if (this.pendingImageMessages.size === 0)
             return messages;
@@ -307,6 +329,7 @@ export class TurnLoop {
     recordResponseUsage(usage) {
         this.currentTurnUsage = addTokenUsage(this.currentTurnUsage, usage);
         this.currentCumulativeUsage = this.deps.recordCumulativeUsage?.(usage);
+        this.deps.recordCacheReadDiagnostics?.(usage);
     }
     emitCtxFromUsage(usage, messages) {
         if (!this.config.onStream)
@@ -379,6 +402,10 @@ export class TurnLoop {
         let messages = [...initialMessages];
         let finalText = "";
         const budgetTracker = createBudgetTracker();
+        // Recent execution evidence for the built-in Goal judge. Values enter this
+        // window only after irreversible sensitive-data removal, non-text omission,
+        // and per-item truncation at the current-round ToolResult boundary.
+        const goalToolResults = [];
         // Goal-mode run-scoped budget tracker (P0). Null when no goal. Stamps a
         // wall-clock start now and accumulates prompt+completion tokens across
         // every turn; the guardrail below force-stops the run once any configured
@@ -425,7 +452,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.
-                this.consumeQueuedSteer(messages, "normal_step");
+                await 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
@@ -487,6 +514,7 @@ export class TurnLoop {
                 // pendingImageMessages are preserved through this next model request.
                 const hasPendingSensitiveToolResults = this.sensitiveToolResultRedactions.size > 0;
                 messages = this.prepareMessagesForModel(messages);
+                messages = this.stripVolatileContextMessages(messages);
                 if (hasPendingSensitiveToolResults) {
                     tlog.info("turn.sensitive_tool_result_context_management_skipped", {
                         cat: "turn",
@@ -531,6 +559,7 @@ export class TurnLoop {
                         messages.push(compactInjection);
                     }
                 }
+                messages = this.appendVolatileContextMessages(messages);
                 // Model call (with streaming fallback and max_output_tokens continuation)
                 // Track tool IDs streamed during this turn to avoid duplicate UI events
                 this.streamedToolIds.clear();
@@ -602,7 +631,8 @@ export class TurnLoop {
                 // compaction decisions use hybrid (actual + delta) estimation rather than
                 // pure heuristics. Without this the manager falls back to char/4 estimates.
                 if (response.usage?.promptTokens !== undefined) {
-                    const anchor = this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length, messages);
+                    const contextAnchorMessages = this.stripVolatileContextMessages(messages);
+                    const anchor = this.deps.contextManager.recordActualUsage(response.usage.promptTokens, contextAnchorMessages.length, contextAnchorMessages);
                     if (anchor)
                         this.deps.recordContextUsageAnchor?.(anchor);
                 }
@@ -692,7 +722,10 @@ export class TurnLoop {
                 // is force-stopped regardless of what the model wants to do next (stop OR
                 // continue with tool calls). This is the unattended-safety backstop, so
                 // it sits BEFORE the "tool calls?" branch — both paths pass the gate.
-                if (goalTracker && goalBudgetExceeded(goalTracker, Date.now())) {
+                const budgetTermination = goalTracker
+                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                    : undefined;
+                if (goalTracker && budgetTermination) {
                     tlog.info("turn.goal_budget_exhausted", {
                         cat: "goal",
                         tokensUsed: goalTracker.tokensUsed,
@@ -707,7 +740,12 @@ export class TurnLoop {
                             content: "（Goal 预算已耗尽，强制停止。）",
                         },
                     });
-                    return { text: finalText, reason: "goal_budget_exhausted", messages };
+                    return {
+                        text: finalText,
+                        reason: "goal_budget_exhausted",
+                        messages,
+                        goalTermination: budgetTermination,
+                    };
                 }
                 // Post-check: tool calls?
                 if (response.toolCalls.length === 0) {
@@ -722,7 +760,7 @@ export class TurnLoop {
                         hasToolUse: false,
                     });
                     messages.push({ role: "assistant", content: finalText });
-                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     // on_stop seam: the model wants to stop. Give handlers (Goal mode)
@@ -731,6 +769,23 @@ export class TurnLoop {
                     // we run another turn instead of returning. Bounded by
                     // maxStopBlocks (consecutive) and the outer maxTurns ceiling.
                     const maxStopBlocks = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+                    if (goalTracker) {
+                        this.deps.updateGoalJudgeContext?.({
+                            toolResults: goalToolResults.map((item) => ({
+                                ...item,
+                            })),
+                            progress: {
+                                turnCount: this.turnCount,
+                                stopRound: this.stopBlockCount + 1,
+                                elapsedMs: Math.max(0, Date.now() - goalTracker.startedAtMs),
+                                tokensUsed: goalTracker.tokensUsed,
+                                tokenBudget: goalTracker.goal.tokenBudget,
+                                timeBudgetMs: goalTracker.goal.timeBudgetMs,
+                                maxTurns: this.config.maxTurns,
+                                maxStopBlocks,
+                            },
+                        });
+                    }
                     const stopHook = await this.emitHook("on_stop", {
                         goal: this.config.goal,
                         finalText,
@@ -775,6 +830,7 @@ export class TurnLoop {
                         });
                         continue;
                     }
+                    let goalTermination;
                     if (stopHook.continueSession && this.stopBlockCount >= maxStopBlocks) {
                         // Cap hit: stop anyway, but tell the user why we're not looping
                         // forever on an unsatisfiable goal.
@@ -788,6 +844,7 @@ export class TurnLoop {
                             status: "exhausted",
                             round: this.stopBlockCount,
                         });
+                        goalTermination = "stop_blocks_exhausted";
                         this.config.onStream?.({
                             type: "assistant_message",
                             messageId: assistantMessageId,
@@ -807,11 +864,11 @@ export class TurnLoop {
                         });
                     }
                     this.stopBlockCount = 0;
-                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     messages = this.redactConsumedSensitiveToolResults(messages);
-                    return { text: finalText, reason: "completed", messages };
+                    return { text: finalText, reason: "completed", messages, goalTermination };
                 }
                 // Tool execution phase
                 tlog.info("turn.tool_use", {
@@ -854,6 +911,13 @@ export class TurnLoop {
                 // Record results in transcript and stream
                 const resultBlocks = [];
                 for (const result of results) {
+                    if (goalTracker) {
+                        goalToolResults.push(projectGoalJudgeToolResult(result, this.turnCount));
+                        // The prompt renderer keeps at most 12, but retaining a few extra
+                        // bounded projections lets its total-char budget choose the newest useful subset.
+                        if (goalToolResults.length > 20)
+                            goalToolResults.splice(0, goalToolResults.length - 20);
+                    }
                     resultBlocks.push(toolResultToBlock(result));
                     const streamResult = toolResultForDisplay(result);
                     const transcriptResult = toolResultTranscriptText(result);
@@ -930,7 +994,7 @@ export class TurnLoop {
                     tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
                     this.stopBlockCount = 0;
                     this.deps.clearPersistedGoal?.();
-                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     messages = this.redactConsumedSensitiveToolResults(messages);
@@ -946,7 +1010,7 @@ export class TurnLoop {
                     tlog.info("turn.goal_user_cancelled", { cat: "goal" });
                     this.stopBlockCount = 0;
                     this.deps.clearPersistedGoal?.();
-                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     return { text: finalText, reason: "completed", messages };
@@ -966,7 +1030,7 @@ export class TurnLoop {
                         message: { role: "assistant", content: finalText },
                     });
                     messages.push({ role: "assistant", content: finalText });
-                    if (this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                    if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
                     messages = this.redactConsumedSensitiveToolResults(messages);
@@ -1048,7 +1112,7 @@ export class TurnLoop {
             maxTurns: this.config.maxTurns,
             turnCount: this.turnCount,
         });
-        this.consumeQueuedSteer(messages, "finalize_backfill");
+        await this.consumeQueuedSteer(messages, "finalize_backfill");
         const hasPendingSensitiveToolResults = this.sensitiveToolResultRedactions.size > 0;
         messages = this.prepareMessagesForModel(messages);
         if (hasPendingSensitiveToolResults) {
@@ -1086,7 +1150,12 @@ export class TurnLoop {
             messages.push({ role: "assistant", content: finalText });
         }
         messages = this.redactConsumedSensitiveToolResults(messages);
-        return { text: finalText, reason: "max_turns", messages };
+        return {
+            text: finalText,
+            reason: "max_turns",
+            messages,
+            ...(this.config.goal ? { goalTermination: "max_turns_exhausted" } : {}),
+        };
     }
     /**
      * Call model with streaming fallback.
@@ -1168,10 +1237,12 @@ export class TurnLoop {
     get currentTurn() {
         return this.turnCount;
     }
-    consumeQueuedSteer(messages, source) {
+    async consumeQueuedSteer(messages, source) {
         const steered = this.deps.consumeSteer?.(source) ?? [];
         let consumed = false;
-        for (const { id, text, clientMessageId } of steered) {
+        for (let index = 0; index < steered.length; index++) {
+            const item = steered[index];
+            const { id, text, clientMessageId } = item;
             if (!text)
                 continue;
             if (clientMessageId && this.deps.claimClientMessageId?.(clientMessageId, "steer") === false) {
@@ -1183,9 +1254,33 @@ export class TurnLoop {
                 });
                 continue;
             }
+            let content;
+            try {
+                content = this.deps.buildSteerUserMessageContent
+                    ? await this.deps.buildSteerUserMessageContent(item)
+                    : text;
+            }
+            catch (err) {
+                if (clientMessageId)
+                    this.deps.releaseClientMessageId?.(clientMessageId);
+                const pendingSuffix = steered.slice(index);
+                this.deps.restoreSteer?.(pendingSuffix);
+                logger.warn("steer.prepare.failed_requeued", {
+                    clientMessageId,
+                    steerId: id,
+                    sessionId: this.deps.sessionId,
+                    source,
+                    restoredCount: pendingSuffix.length,
+                    error: err.message,
+                });
+                break;
+            }
             consumed = true;
-            messages.push({ role: "user", content: text });
-            this.deps.transcript.appendMessage("user", text, { steerId: id, clientMessageId });
+            this.deps.setOriginClientMessageId?.(clientMessageId);
+            const message = { role: "user", content };
+            messages.push(message);
+            this.trackFreshImageMessage(message);
+            this.deps.transcript.appendMessage("user", content, { steerId: id, clientMessageId });
             this.config.onStream?.({ type: "steer_injected", text, id });
         }
         return consumed;

package/dist/hooks/goal-stop-hook.d.ts

@@ -1,5 +1,5 @@
 import type { HookHandler } from "./registry.js";
-import type { LLMResponse } from "../types.js";
+import type { LLMResponse, ToolResult } from "../types.js";
 import { type GoalConfig } from "../engine/goal.js";
 /** Narrow LLM surface the judge needs — just a one-shot completion. */
 export interface GoalJudgeLLM {
@@ -53,6 +53,38 @@ export interface GoalStopHookOptions {
      * `() => new Date()`.
      */
     now?: () => Date;
+    /**
+     * Private runtime evidence supplied by TurnLoop immediately before on_stop.
+     * It deliberately lives on this closure rather than HookContext.data so
+     * third-party/public stop hooks do not gain access to tool output.
+     */
+    getJudgeContext?: () => GoalJudgeRuntimeContext | undefined;
+}
+export interface GoalJudgeRuntimeContext {
+    /** Recent irreversible projections from this run, newest evidence retained by TurnLoop. */
+    toolResults: GoalJudgeToolResult[];
+    progress: {
+        turnCount: number;
+        /** One-based natural-stop/judge round for this run. */
+        stopRound: number;
+        elapsedMs: number;
+        tokensUsed: number;
+        tokenBudget?: number;
+        timeBudgetMs?: number;
+        maxTurns?: number;
+        maxStopBlocks?: number;
+    };
+}
+export interface GoalJudgeToolResult {
+    turnCount: number;
+    toolName: string;
+    status: "success" | "error";
+    /** Bounded plain text only; absent for sensitive or purely non-text results. */
+    text?: string;
+    /** True when image/binary/structured blocks were replaced with a placeholder. */
+    omittedNonText?: true;
 }
+/** Build the bounded, irreversible value retained beyond the current model round. */
+export declare function projectGoalJudgeToolResult(result: ToolResult, turnCount: number): GoalJudgeToolResult;
 export declare function createGoalStopHook(opts: GoalStopHookOptions): HookHandler;
 export {};