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

package/dist/engine/resolve-llm-config.js

@@ -0,0 +1,44 @@
+import { getMergedCatalog } from "../model-catalog/index.js";
+import { modelEntriesFromConnections } from "./model-connections-pool.js";
+import { ModelPool } from "../llm/model-pool.js";
+export function resolveLLMConfigForTag(settings, tag, preferredInstanceId) {
+    const connections = settings.modelConnections;
+    if (!Array.isArray(connections) || connections.length === 0)
+        return null;
+    const credentials = settings.credentials;
+    const catalog = getMergedCatalog();
+    const entries = modelEntriesFromConnections(connections, (Array.isArray(credentials) ? credentials : []), catalog);
+    if (entries.length === 0)
+        return null;
+    // entry.key === connection.id(见 modelEntriesFromConnections)。
+    const defaultId = settings.defaults?.text;
+    const pick = (preferredInstanceId && entries.find((e) => e.key === preferredInstanceId)) ||
+        (defaultId && entries.find((e) => e.key === defaultId)) ||
+        entries[0];
+    if (!pick)
+        return null;
+    // 用户显式选了 default/preferred 但它解析不到(连接的 catalogId 被删 →
+    // modelEntriesFromConnections 静默过滤掉)→ 这里 find 落空、悄悄回退到 entries[0]
+    // 是「换了个模型还不告诉你」。不改回退行为(有可用连接就用),但出一条 warn 让
+    // 静默替换可见(否则用户以为还在用选的那个)。
+    const wanted = preferredInstanceId ?? defaultId;
+    if (wanted && pick.key !== wanted) {
+        console.warn(`[resolveLLMConfigForTag] 偏好/默认连接 "${wanted}" 解析不到(catalogId 可能已删)— 回退到 "${pick.key}"。`);
+    }
+    // The picked connection's catalog template needs a key but none resolved
+    // (credentialId missing/points at a deleted credential). Returning null here
+    // routes to the caller's existing clean "没有可用的文本模型连接 … 请在「连接」
+    // 页添加并填写凭证" message + exit, instead of silently building a config with
+    // apiKey:undefined that only fails later as a cryptic provider 401. In
+    // CONTRACT: this fn's null already means "no USABLE connection for this tag".
+    // resolveInstance's no-crash (apiKey:undefined) behavior is untouched — this
+    // gate is one layer up where usability is decided.
+    if (pick.needsKey !== false && !pick.apiKey) {
+        console.warn(`[resolveLLMConfigForTag] 连接 "${pick.key}" 需要密钥但未解析到凭证(credentialId 缺失或指向已删凭证)— 视为该 tag 无可用连接。`);
+        return null;
+    }
+    // 临时 pool 复用 toLLMConfig 的全部映射逻辑(reasoning/headers/providerKind 等)。
+    const pool = new ModelPool([]);
+    pool.register(pick);
+    return pool.toLLMConfig(pick);
+}

package/dist/engine/runtime.d.ts

@@ -23,6 +23,8 @@ export declare class EngineRuntime {
     readonly costTracker: CostTracker;
     private sandboxCache;
     constructor(opts: EngineRuntimeOptions);
+    clearModels(): void;
+    reloadModelsFromSettings(): void;
     /**
      * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
      *

package/dist/engine/runtime.js

@@ -1,4 +1,8 @@
+import { getMergedCatalog } from "../model-catalog/index.js";
+import { modelEntriesFromConnections } from "./model-connections-pool.js";
+import { defaultCacheDir } from "../llm/model-cache.js";
 import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
+import { sandboxCacheKey } from "./sandbox-cache-key.js";
 /**
  * Shared read-only resources used by all Engine instances in a worker.
  * Mutable per-session state stays on Engine itself.
@@ -21,6 +25,28 @@ export class EngineRuntime {
         this.mcpPool = opts.mcpPool;
         this.costTracker = opts.costTracker;
     }
+    clearModels() {
+        this.modelPool.clear();
+    }
+    reloadModelsFromSettings() {
+        const settings = this.settings.load();
+        const connections = settings.modelConnections ?? [];
+        const credentials = settings.credentials ?? [];
+        const catalog = getMergedCatalog();
+        const entries = modelEntriesFromConnections(connections, credentials, catalog);
+        this.modelPool.clear();
+        if (entries.length === 0)
+            return;
+        for (const entry of entries)
+            this.modelPool.register(entry);
+        if (entries.length > 0) {
+            const defaultText = settings.defaults?.text;
+            const key = defaultText && entries.some((e) => e.key === defaultText) ? defaultText : entries[0].key;
+            this.modelPool.switch(key);
+            this.modelPool.setCacheDir(defaultCacheDir());
+            this.modelPool.reloadCachedContextWindows();
+        }
+    }
     /**
      * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
      *
@@ -31,7 +57,7 @@ export class EngineRuntime {
      * violate standard §S4 fail-closed rule.
      */
     resolveSandbox(config, cwd) {
-        const key = `${config.mode}:${cwd}`;
+        const key = sandboxCacheKey(config, cwd);
         let cached = this.sandboxCache.get(key);
         if (!cached) {
             cached = resolveSandboxBackend(config, cwd);

package/dist/engine/sandbox-cache-key.d.ts

@@ -0,0 +1,10 @@
+/**
+ * sandboxCacheKey — cache key for a resolved sandbox backend. Includes every
+ * field that affects the backend (mode, network, writableRoots, deniedReads)
+ * plus cwd. The key was previously `${mode}:${cwd}`, which ignored network /
+ * roots / reads — so editing those in 设置页 hit the stale cached backend and
+ * didn't take effect until app restart. Stable JSON shape so equal configs map
+ * to equal keys.
+ */
+import type { SandboxConfig } from "../tool-system/sandbox/index.js";
+export declare function sandboxCacheKey(config: SandboxConfig, cwd: string): string;

package/dist/engine/sandbox-cache-key.js

@@ -0,0 +1,9 @@
+export function sandboxCacheKey(config, cwd) {
+    return JSON.stringify({
+        mode: config.mode,
+        network: config.network,
+        writableRoots: config.writableRoots,
+        deniedReads: config.deniedReads,
+        cwd,
+    });
+}

package/dist/engine/sandbox-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * resolveSandboxConfig — pick the sandbox config for a run, reading the
+ * 设置页's settings.sandbox so a project-scoped sandbox setting actually takes
+ * effect. Priority: explicit config.sandbox → settings.sandbox.mode → per-run
+ * default (headless=auto, REPL/desktop=off).
+ *
+ * Background: the engine previously only honored config.sandbox, which the
+ * desktop host never passes — so a user enabling sandbox in 设置页 had no
+ * effect. This bridges settings → run config.
+ * See memory project_10_review_bug_list #9.
+ */
+import { type SandboxConfig, type SandboxMode } from "../tool-system/sandbox/index.js";
+/** The shape of settings.sandbox (all fields optional). */
+export interface SettingsSandbox {
+    mode?: SandboxMode;
+    network?: "allow" | "deny";
+    writableRoots?: string[];
+    deniedReads?: string[];
+}
+/**
+ * Three-layer resolve. Priority:
+ *   1. config.sandbox — explicit host-passed.
+ *   2. project settings.sandbox (has mode) — overrides global.
+ *   3. global settings.sandbox (has mode) — what a project "follows".
+ *   4. per-run default: headless → auto, desktop/REPL → off.
+ *
+ * A layer without `mode` is "unset / 跟随上一层" — pass unmerged per-scope
+ * values so a project that wrote nothing genuinely follows global (a merged
+ * value would make every project look like it set global's mode).
+ */
+export declare function resolveSandboxConfig(configSandbox: SandboxConfig | undefined, projectSandbox: SettingsSandbox | undefined, globalSandbox: SettingsSandbox | undefined, headless: boolean): SandboxConfig;

package/dist/engine/sandbox-config.js

@@ -0,0 +1,38 @@
+/**
+ * resolveSandboxConfig — pick the sandbox config for a run, reading the
+ * 设置页's settings.sandbox so a project-scoped sandbox setting actually takes
+ * effect. Priority: explicit config.sandbox → settings.sandbox.mode → per-run
+ * default (headless=auto, REPL/desktop=off).
+ *
+ * Background: the engine previously only honored config.sandbox, which the
+ * desktop host never passes — so a user enabling sandbox in 设置页 had no
+ * effect. This bridges settings → run config.
+ * See memory project_10_review_bug_list #9.
+ */
+import { defaultSandboxConfig } from "../tool-system/sandbox/index.js";
+/**
+ * Three-layer resolve. Priority:
+ *   1. config.sandbox — explicit host-passed.
+ *   2. project settings.sandbox (has mode) — overrides global.
+ *   3. global settings.sandbox (has mode) — what a project "follows".
+ *   4. per-run default: headless → auto, desktop/REPL → off.
+ *
+ * A layer without `mode` is "unset / 跟随上一层" — pass unmerged per-scope
+ * values so a project that wrote nothing genuinely follows global (a merged
+ * value would make every project look like it set global's mode).
+ */
+export function resolveSandboxConfig(configSandbox, projectSandbox, globalSandbox, headless) {
+    if (configSandbox)
+        return configSandbox;
+    const layer = projectSandbox?.mode ? projectSandbox : globalSandbox?.mode ? globalSandbox : undefined;
+    if (layer?.mode) {
+        const base = defaultSandboxConfig(layer.mode);
+        return {
+            mode: layer.mode,
+            network: layer.network ?? base.network,
+            writableRoots: layer.writableRoots ?? base.writableRoots,
+            deniedReads: layer.deniedReads ?? base.deniedReads,
+        };
+    }
+    return defaultSandboxConfig(headless ? "auto" : "off");
+}

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

@@ -0,0 +1,31 @@
+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.
+ *
+ * The LLM client is recreated per `engine.run()`, so its `getUsage()` totals
+ * count only the current run and start from zero each run. To get a true
+ * session cumulative we add the run's running total onto the baseline captured
+ * at run start (the value persisted from prior runs).
+ *
+ * Crucially this is `baseline + current`, NOT `baseline += current`: the
+ * turn-boundary heartbeat fires many times within one run, each reading the
+ * run's growing total. Recomputing `baseline + current` every time is
+ * idempotent — it never double-counts — whereas a `+=` would add the running
+ * total repeatedly. Feed the folded result back as the baseline only across
+ * run boundaries (new client, fresh run total).
+ */
+export declare function foldRunUsage(baseline: TokenUsage, runUsage: LLMUsageTracker): TokenUsage;

package/dist/engine/session-usage.js

@@ -0,0 +1,81 @@
+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.
+ *
+ * The LLM client is recreated per `engine.run()`, so its `getUsage()` totals
+ * count only the current run and start from zero each run. To get a true
+ * session cumulative we add the run's running total onto the baseline captured
+ * at run start (the value persisted from prior runs).
+ *
+ * Crucially this is `baseline + current`, NOT `baseline += current`: the
+ * turn-boundary heartbeat fires many times within one run, each reading the
+ * run's growing total. Recomputing `baseline + current` every time is
+ * idempotent — it never double-counts — whereas a `+=` would add the running
+ * total repeatedly. Feed the folded result back as the baseline only across
+ * run boundaries (new client, fresh run total).
+ */
+export function foldRunUsage(baseline, runUsage) {
+    return {
+        promptTokens: baseline.promptTokens + runUsage.totalPromptTokens,
+        completionTokens: baseline.completionTokens + runUsage.totalCompletionTokens,
+        totalTokens: baseline.totalTokens + runUsage.totalTokens,
+        cacheReadTokens: (baseline.cacheReadTokens ?? 0) + runUsage.totalCacheReadTokens,
+        cacheCreationTokens: (baseline.cacheCreationTokens ?? 0) + runUsage.totalCacheCreationTokens,
+    };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Step-gap steering queue — pure helpers over a per-session list of pending
+ * user messages. Each entry carries a stable `id` so the host can (a) match the
+ * later `steer_injected` event back to the queued draft it showed in the UI and
+ * (b) revoke a still-pending entry via `unsteer` before the turn loop consumes
+ * it. Pure + side-effect-free so it unit-tests without the Engine/TurnLoop
+ * harness (same rationale as the renderer's queuedInput.ts).
+ */
+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, 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
+ * each step boundary.
+ */
+export declare function consumeSteerItems(list: SteerItem[]): {
+    drained: SteerItem[];
+    rest: SteerItem[];
+};
+/**
+ * Remove a still-pending entry by id (the 撤回 path). Returns the new list and
+ * whether anything was removed — `false` means it was already consumed (the
+ * host can't take it back; it has already been spliced into the run).
+ */
+export declare function removeSteerItem(list: SteerItem[], id: string): {
+    list: SteerItem[];
+    removed: boolean;
+};

package/dist/engine/steer-queue.js

@@ -0,0 +1,26 @@
+/** Append a steer entry. Blank text is dropped (returns the list unchanged). */
+export function enqueueSteerItem(list, id, text, clientMessageId) {
+    const t = text?.trim();
+    if (!id || !t)
+        return list;
+    return [...list, { id, text: t, ...(clientMessageId ? { clientMessageId } : {}) }];
+}
+/**
+ * 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
+ * each step boundary.
+ */
+export function consumeSteerItems(list) {
+    if (list.length === 0)
+        return { drained: [], rest: [] };
+    return { drained: list, rest: [] };
+}
+/**
+ * Remove a still-pending entry by id (the 撤回 path). Returns the new list and
+ * whether anything was removed — `false` means it was already consumed (the
+ * host can't take it back; it has already been spliced into the run).
+ */
+export function removeSteerItem(list, id) {
+    const next = list.filter((item) => item.id !== id);
+    return { list: next, removed: next.length !== list.length };
+}

package/dist/engine/streaming-tool-queue.d.ts

@@ -17,6 +17,7 @@ export declare class StreamingToolQueue {
     private readonly pending;
     private readonly unsafeQueue;
     private readonly callOrder;
+    private readonly toolNameById;
     private draining;
     constructor(executor: ToolExecutor);
     /**
@@ -27,8 +28,19 @@ export declare class StreamingToolQueue {
     /**
      * Execute all remaining unsafe tools sequentially, then await all results.
      * Returns results in original enqueue order.
+     *
+     * A tool's promise can REJECT — not just resolve to an error ToolResult —
+     * because permission.handleAsk (and pre_tool_use "ask") throw outside
+     * executeSingle's try/catch. We must never let one rejection (a) abort the
+     * drain and lose the other tools' results, or (b) leave a hole that surfaces
+     * as `undefined` downstream (toolResultToBlock would crash on it). So every
+     * await is funneled through toResult(), which converts a thrown value into a
+     * synthetic error ToolResult, and any id still missing at the end is filled
+     * with one too.
      */
     drain(): Promise<ToolResult[]>;
+    /** Await a tool promise, converting a rejection into an error ToolResult. */
+    private toResult;
     /** Number of tools currently enqueued or executing. */
     get size(): number;
 }

package/dist/engine/streaming-tool-queue.js

@@ -15,6 +15,7 @@ export class StreamingToolQueue {
     pending = new Map();
     unsafeQueue = [];
     callOrder = [];
+    toolNameById = new Map();
     draining = false;
     constructor(executor) {
         this.executor = executor;
@@ -25,9 +26,14 @@ export class StreamingToolQueue {
      */
     enqueue(call) {
         this.callOrder.push(call.id);
+        this.toolNameById.set(call.id, call.toolName);
         if (this.executor.isConcurrencySafe(call.toolName)) {
-            // Start immediately
-            this.pending.set(call.id, this.executor.executeSingle(call));
+            // Start immediately. Attach a no-op catch so a synchronous/early rejection
+            // doesn't surface as an unhandledRejection before drain() awaits it; the
+            // real handling (→ error ToolResult) happens in drain()/toResult().
+            const p = this.executor.executeSingle(call);
+            p.catch(() => { });
+            this.pending.set(call.id, p);
         }
         else {
             this.unsafeQueue.push(call);
@@ -36,23 +42,57 @@ export class StreamingToolQueue {
     /**
      * Execute all remaining unsafe tools sequentially, then await all results.
      * Returns results in original enqueue order.
+     *
+     * A tool's promise can REJECT — not just resolve to an error ToolResult —
+     * because permission.handleAsk (and pre_tool_use "ask") throw outside
+     * executeSingle's try/catch. We must never let one rejection (a) abort the
+     * drain and lose the other tools' results, or (b) leave a hole that surfaces
+     * as `undefined` downstream (toolResultToBlock would crash on it). So every
+     * await is funneled through toResult(), which converts a thrown value into a
+     * synthetic error ToolResult, and any id still missing at the end is filled
+     * with one too.
      */
     async drain() {
         if (this.draining)
             throw new Error("StreamingToolQueue already draining");
         this.draining = true;
-        // Execute unsafe tools sequentially
+        const resultMap = new Map();
+        // Execute unsafe tools sequentially. A rejection here must not stop the
+        // remaining unsafe tools from running.
         for (const call of this.unsafeQueue) {
-            this.pending.set(call.id, this.executor.executeSingle(call));
-            await this.pending.get(call.id);
+            const p = this.executor.executeSingle(call);
+            this.pending.set(call.id, p);
+            resultMap.set(call.id, await this.toResult(call.id, call.toolName, p));
         }
-        // Await all results
-        const resultMap = new Map();
+        // Await all results (concurrency-safe tools started at enqueue time).
         for (const [id, promise] of this.pending) {
-            resultMap.set(id, await promise);
+            if (resultMap.has(id))
+                continue; // already drained above
+            const toolName = this.toolNameById.get(id) ?? "unknown";
+            resultMap.set(id, await this.toResult(id, toolName, promise));
+        }
+        // Return in original order, with a synthetic error for any id that somehow
+        // never produced a result (defensive — should not happen now).
+        return this.callOrder.map((id) => resultMap.get(id) ?? {
+            id,
+            toolName: this.toolNameById.get(id) ?? "unknown",
+            error: "Tool execution produced no result.",
+            isError: true,
+        });
+    }
+    /** Await a tool promise, converting a rejection into an error ToolResult. */
+    async toResult(id, toolName, p) {
+        try {
+            return await p;
+        }
+        catch (err) {
+            return {
+                id,
+                toolName,
+                error: err instanceof Error ? err.message : String(err),
+                isError: true,
+            };
         }
-        // Return in original order
-        return this.callOrder.map((id) => resultMap.get(id));
     }
     /** Number of tools currently enqueued or executing. */
     get size() {

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

@@ -4,19 +4,27 @@
  * 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 GoalConfig } from "./goal.js";
+import { type CumulativeUsageCounters } from "./session-usage.js";
+import { type GoalConfig, type GoalExtension } from "./goal.js";
 export interface TurnLoopConfig {
     maxTurns: number;
     maxToolCallsPerTurn: number;
     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
@@ -35,7 +43,8 @@ export interface TurnLoopConfig {
      * 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 8. Independent of maxTurns, which still bounds total turns.
+     * to GOAL_DEFAULT_MAX_STOP_BLOCKS. Independent of maxTurns, which still
+     * bounds total turns.
      */
     maxStopBlocks?: number;
 }
@@ -74,6 +83,35 @@ 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
+     * 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?: (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
+     * 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;
@@ -88,7 +126,7 @@ export interface TurnLoopResult {
 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;
@@ -101,12 +139,49 @@ 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
      * 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.
@@ -114,6 +189,19 @@ 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 prepareMessagesForModel;
+    private markPendingImagesConsumed;
+    private trackFreshImageMessage;
     private emitHook;
     /**
      * Emit a usage_update so the UI ctx bar reflects current message-array
@@ -123,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.
@@ -134,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).