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

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

@@ -10,9 +10,10 @@ 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 { type GoalJudgeRuntimeContext } from "../hooks/goal-stop-hook.js";
 import { Transcript } from "../session/transcript.js";
 import { type CumulativeUsageCounters } from "./session-usage.js";
-import { type GoalConfig, type GoalExtension } from "./goal.js";
+import { type GoalConfig, type GoalExtension, type GoalTerminationReason } from "./goal.js";
 export interface TurnLoopConfig {
     maxTurns: number;
     maxToolCallsPerTurn: number;
@@ -25,6 +26,11 @@ export interface TurnLoopConfig {
      * response, then downgrades them to placeholders in the working history.
      */
     freshImageMessages?: Iterable<Message>;
+    /**
+     * Per-run injected context that must be visible to the model but must not be
+     * summarized into durable history. Engine uses this for dynamicContext.
+     */
+    volatileContextMessages?: 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
@@ -88,6 +94,11 @@ export interface TurnLoopDeps {
      * Returns the updated counters so usage_update can carry both metric scopes.
      */
     recordCumulativeUsage?: (usage: TokenUsage) => CumulativeUsageCounters;
+    /**
+     * Lightweight per-session prompt-cache diagnostic, owned by Engine because it
+     * needs memory across TurnLoop instances.
+     */
+    recordCacheReadDiagnostics?: (usage: TokenUsage) => void;
     /** Persist the latest context-estimation anchor derived from provider usage. */
     recordContextUsageAnchor?: (anchor: ContextUsageAnchor) => void;
     /**
@@ -99,12 +110,20 @@ export interface TurnLoopDeps {
      * tests (turn loop tolerates undefined).
      */
     consumeSteer?: (source?: "normal_step" | "finalize_backfill") => SteerItem[];
+    /** Restore steer items whose model-facing content could not be prepared. */
+    restoreSteer?: (items: SteerItem[]) => void;
+    /** Build model-facing content for a queued steer item, including attachments. */
+    buildSteerUserMessageContent?: (item: SteerItem) => string | ContentBlock[] | Promise<string | ContentBlock[]>;
     /**
      * 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;
+    /** Release a steer id reservation when preparation fails before persistence. */
+    releaseClientMessageId?: (clientMessageId: string) => void;
+    /** Make tools launched after an injected steer attribute side effects to that steer. */
+    setOriginClientMessageId?: (clientMessageId: string | undefined) => void;
     /**
      * 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
@@ -114,11 +133,18 @@ export interface TurnLoopDeps {
      * goalTracker short-circuit still stops the run).
      */
     clearPersistedGoal?: () => void;
+    /**
+     * Private Goal-judge evidence seam. Engine stores this snapshot in the
+     * built-in judge closure; it is never added to the public on_stop context.
+     */
+    updateGoalJudgeContext?: (context: GoalJudgeRuntimeContext) => void;
 }
 export interface TurnLoopResult {
     text: string;
     reason: TerminalReason;
     messages: Message[];
+    /** Goal-specific forced terminal outcome; public TerminalReason stays stable. */
+    goalTermination?: GoalTerminationReason;
 }
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
@@ -145,6 +171,11 @@ export declare class TurnLoop {
     private currentCumulativeUsage;
     private readonly sensitiveToolResultRedactions;
     private readonly pendingImageMessages;
+    private readonly volatileContextMessages;
+    /** Last outer-loop turn for which the model returned a complete response. */
+    private lastCompletedModelTurn;
+    /** Last model turn whose transcript/persistence boundary was finalized. */
+    private lastFinalizedTurn;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -177,6 +208,13 @@ export declare class TurnLoop {
         timeBudgetMs?: number;
         maxStopBlocks: number;
     };
+    /**
+     * Private Goal-judge accounting seam. Judge calls bypass ModelFacade, so the
+     * Engine forwards their provider usage here while the run-scoped tracker is
+     * live. The returned reason lets the hook suppress verdict side effects when
+     * this very request crossed a hard token/time budget.
+     */
+    recordGoalJudgeUsage(usage: TokenUsage | undefined): Extract<GoalTerminationReason, "token_budget_exhausted" | "time_budget_exhausted"> | undefined;
     /**
      * 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
@@ -202,7 +240,16 @@ export declare class TurnLoop {
      * for one Stop still writes a single marker.
      */
     private markStopped;
+    /**
+     * Close one completed model turn exactly once. The transcript boundary must
+     * be durable before the Engine flushes usage, heartbeat, and turnCount via
+     * onTurnBoundary, so crash recovery never folds two assistant responses into
+     * the same transcript turn or observes state ahead of the transcript.
+     */
+    private finalizeModelTurn;
     private prepareMessagesForModel;
+    private stripVolatileContextMessages;
+    private appendVolatileContextMessages;
     private markPendingImagesConsumed;
     private redactConsumedSensitiveToolResults;
     private modelCallRecordingOptions;