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

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

@@ -4,12 +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 } from "../types.js";
+import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult } 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 GoalConfig, type GoalExtension } from "./goal.js";
 export interface TurnLoopConfig {
     maxTurns: number;
     maxToolCallsPerTurn: number;
@@ -22,6 +24,22 @@ export interface TurnLoopConfig {
      * the on-disk turnCount/status frozen at the last completion.
      */
     onTurnBoundary?: (turnCount: number) => void;
+    /**
+     * Goal mode: the normalized GoalConfig (objective + optional token/time
+     * budgets), passed to on_stop handlers via ctx.data.goal so the
+     * GoalStopHook can judge completion. The run-scoped budget tracker reads
+     * the budgets to force-stop an unattended run. Undefined when no goal is
+     * set (on_stop still fires but built-in Goal handler is a no-op without it).
+     */
+    goal?: GoalConfig;
+    /**
+     * Max consecutive times an on_stop handler may block termination before
+     * the loop forces a stop, mirroring Claude Code's stop-hook block cap.
+     * Resets to 0 whenever a turn completes without being blocked. Defaults
+     * to GOAL_DEFAULT_MAX_STOP_BLOCKS. Independent of maxTurns, which still
+     * bounds total turns.
+     */
+    maxStopBlocks?: number;
 }
 export interface CtxOverheadStore {
     /** Tokens for system prompt + tool defs, derived from provider's promptTokens. */
@@ -58,15 +76,39 @@ export interface TurnLoopDeps {
         before: number;
         after: number;
     } | null;
+    /**
+     * 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
+     * of each turn so the messages join the next LLM request WITHOUT aborting the
+     * current run — the "不打断、步间隙注入" path (vs the relay abort+resend).
+     * Returns [] when nothing is queued. Wired by Engine; absent in standalone
+     * tests (turn loop tolerates undefined).
+     */
+    consumeSteer?: () => SteerItem[];
+    /**
+     * 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
+     * current run AND prevents the goal from re-inheriting on the next bare send.
+     * Wired by Engine (delegates to Engine.clearGoal for the running session);
+     * absent in standalone tests (turn loop tolerates undefined — the local
+     * goalTracker short-circuit still stops the run).
+     */
+    clearPersistedGoal?: () => void;
 }
 export interface TurnLoopResult {
     text: string;
     reason: TerminalReason;
     messages: Message[];
 }
+/**
+ * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
+ * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
+ * 用文本(成功用 result,失败用 "Error: ...")。抽成纯函数以便单测。
+ */
+export declare function toolResultToBlock(result: ToolResult): ContentBlock;
 export declare class TurnLoop {
     private readonly deps;
-    private readonly config;
+    private config;
     private turnCount;
     /** Tool IDs already emitted as tool_use_start during streaming (to avoid duplicates). */
     private streamedToolIds;
@@ -79,6 +121,46 @@ export declare class TurnLoop {
     private currentTurnLog;
     /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
     private lastCtxEmit;
+    /**
+     * 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.
+     */
+    private stopBlockCount;
+    /**
+     * 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.
+     */
+    private goalTracker;
+    /**
+     * 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.
+     */
+    private approachAnnounced;
+    /**
+     * 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: GoalExtension): {
+        maxTurns: number;
+        tokenBudget?: number;
+        timeBudgetMs?: number;
+        maxStopBlocks: number;
+    };
+    /**
+     * 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.
+     */
+    private maybeAnnounceApproachingLimit;
     constructor(deps: TurnLoopDeps, config: TurnLoopConfig);
     /**
      * Emit a lifecycle hook with isSubAgent + sessionId auto-merged into data.
@@ -86,6 +168,16 @@ export declare 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.
+     */
+    private markStopped;
     private emitHook;
     /**
      * Emit a usage_update so the UI ctx bar reflects current message-array
@@ -105,13 +197,6 @@ export declare class TurnLoop {
      * If streaming fails, emit tombstone and retry non-streaming.
      */
     private callModelWithFallback;
-    /**
-     * Execute tools with overlap: start concurrent-safe (read-only) tools
-     * immediately in parallel while sequential (write) tools run one-by-one.
-     * Both groups run simultaneously — we don't wait for safe tools to finish
-     * before starting unsafe ones.
-     */
-    private executeToolsOverlapped;
     get currentTurn(): number;
     /**
      * Generate synthetic error tool_results for any dangling tool_use blocks