@cjhyy/code-shell-core 0.6.0-rc.7 → 0.6.0-rc.9

package/dist/engine/engine.js

@@ -11,7 +11,7 @@ import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
 import { getMergedCatalog } from "../model-catalog/index.js";
 import { modelEntriesFromConnections } from "./model-connections-pool.js";
 import { resolveAuxKey } from "./aux-key.js";
-import { foldRunUsage } from "./session-usage.js";
+import { addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
 import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
 import { resolveSandboxConfig } from "./sandbox-config.js";
 import { sandboxCacheKey } from "./sandbox-cache-key.js";
@@ -51,9 +51,9 @@ import { resolveAgentPreset, resolveBuiltinToolNames, } from "../preset/index.js
 import { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
-import { detectProviderFromApiKey, buildModelPool, } from "../onboarding.js";
+import { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { parseTaskWithImages, } from "./parse-task.js";
+import { parseTaskWithImages } from "./parse-task.js";
 import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
 import { tryCompressImages } from "./image-compression.js";
 import { buildSessionTitle } from "./session-title.js";
@@ -61,7 +61,7 @@ import { capabilitiesFor } from "../llm/capabilities/index.js";
 import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
 import { runDreamConsolidation } from "../services/dream-consolidation.js";
 import { join, isAbsolute } from "node:path";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 /**
  * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
  * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
@@ -440,13 +440,15 @@ export class Engine {
         // per-turn path can only hide, not add, so a freshly-`on`'d builtin not in
         // the set needs a session restart to appear.
         const builtinLists = effectiveBuiltinLists(config.enabledBuiltinTools ?? [], config.disabledBuiltinTools ?? [], this.readBuiltinOverride(config.cwd));
-        this.toolRegistry = config.runtime?.toolRegistry ?? new ToolRegistry({
-            builtinTools: resolveBuiltinToolNames({
-                preset: this.preset.name,
-                enabledBuiltinTools: builtinLists.enabledBuiltinTools,
-                disabledBuiltinTools: builtinLists.disabledBuiltinTools,
-            }),
-        });
+        this.toolRegistry =
+            config.runtime?.toolRegistry ??
+                new ToolRegistry({
+                    builtinTools: resolveBuiltinToolNames({
+                        preset: this.preset.name,
+                        enabledBuiltinTools: builtinLists.enabledBuiltinTools,
+                        disabledBuiltinTools: builtinLists.disabledBuiltinTools,
+                    }),
+                });
         this.hooks = new HookRegistry();
         // Installed-plugin hooks — declared in each plugin's hooks/hooks.json.
         // Registered first (priority 80) so user-authored hooks at lower
@@ -637,23 +639,44 @@ export class Engine {
      * Queue a user message to be spliced into the in-flight run for `sessionId`
      * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
      * resend). General-purpose: any host path (UI 引导, future agent coordination,
-     * external triggers) can call it. If no run is active for the session the
-     * message simply waits in the queue and is consumed when that session next
-     * runs (rare race; host normally only steers while busy). No-op on blank text.
+     * external triggers) can call it. If no run is active for this session, reject
+     * without queueing so the host can downgrade to a normal run immediately.
+     * No-op on blank text.
      *
      * `id` is the host's stable queue-entry id. It rides through to the
      * `steer_injected` event (so the host can match the injected bubble back to
      * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
      * entry. A blank id is tolerated but means the entry can't be revoked.
      */
-    enqueueSteer(sessionId, text, id = "") {
-        if (!sessionId)
-            return;
+    enqueueSteer(sessionId, text, id = "", clientMessageId) {
         const q = this.steerQueueBySid.get(sessionId) ?? [];
-        const next = enqueueSteerItem(q, id || `steer-${q.length}`, text);
+        const entryId = id || `steer-${q.length}`;
+        if (!sessionId)
+            return { accepted: false, id: entryId };
+        const activeRunSessionId = this.activeRunSession?.state.sessionId;
+        const active = this.activeTurnLoop !== null && activeRunSessionId === sessionId;
+        if (!active) {
+            logger.info("steer.enqueue.idle_rejected", {
+                sessionId,
+                id: entryId,
+                clientMessageId,
+                activeRunSessionId: activeRunSessionId ?? null,
+                queueLength: q.length,
+            });
+            return { accepted: false, id: entryId };
+        }
+        const next = enqueueSteerItem(q, entryId, text, clientMessageId);
         if (next === q)
-            return; // blank text dropped
+            return { accepted: false, id: entryId }; // blank text dropped
         this.steerQueueBySid.set(sessionId, next);
+        logger.info("steer.enqueue.accepted", {
+            sessionId,
+            id: entryId,
+            clientMessageId,
+            activeRunSessionId,
+            queueLength: next.length,
+        });
+        return { accepted: true, id: entryId };
     }
     /**
      * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
@@ -670,12 +693,20 @@ export class Engine {
         return removed;
     }
     /** Drain + clear the steer queue for a session (turn loop consumes per step). */
-    consumeSteer(sessionId) {
+    consumeSteer(sessionId, source = "normal_step") {
         const q = this.steerQueueBySid.get(sessionId);
         if (!q || q.length === 0)
             return [];
         const { drained, rest } = consumeSteerItems(q);
         this.steerQueueBySid.set(sessionId, rest);
+        logger.info("steer.consume.drained", {
+            sessionId,
+            source,
+            count: drained.length,
+            ids: drained.map((item) => item.id),
+            clientMessageIds: drained.flatMap((item) => item.clientMessageId ? [item.clientMessageId] : []),
+            queueLength: rest.length,
+        });
         return drained;
     }
     /** Wire the cookie→browser injection callback (InjectCredential tool). Same
@@ -916,9 +947,8 @@ export class Engine {
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
                     customSystemPrompt: this.config.customSystemPrompt,
-                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt]
-                        .filter(Boolean)
-                        .join("\n\n") || undefined,
+                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
+                        undefined,
                     responseLanguage: this.config.responseLanguage,
                     userProfile: this.config.userProfile,
                     instructions: this.config.instructions,
@@ -1103,6 +1133,23 @@ export class Engine {
         // call) instead of a try/catch on resume.
         let session;
         let messages;
+        let freshImageMessage;
+        const claimedClientMessageIds = new Set();
+        const claimClientMessageId = (bundle, clientMessageId, source) => {
+            if (!clientMessageId)
+                return true;
+            if (claimedClientMessageIds.has(clientMessageId) ||
+                bundle.transcript.hasClientMessageId(clientMessageId)) {
+                logger.info("engine.client_message.duplicate_ignored", {
+                    sessionId: bundle.state.sessionId,
+                    clientMessageId,
+                    source,
+                });
+                return false;
+            }
+            claimedClientMessageIds.add(clientMessageId);
+            return true;
+        };
         if (options?.sessionId && this.sessionManager.exists(options.sessionId)) {
             session = this.sessionManager.resume(options.sessionId);
             const cachedCompacted = this.compactedMessagesBySession.get(options.sessionId);
@@ -1126,8 +1173,31 @@ export class Engine {
             }
             // Append new user message
             const userMsg = { role: "user", content: userMessageContent };
+            if (!claimClientMessageId(session, options?.clientMessageId, "submit")) {
+                const usage = session.state.tokenUsage ?? {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalTokens: 0,
+                };
+                return {
+                    text: "",
+                    reason: "completed",
+                    sessionId: session.state.sessionId,
+                    turnCount: session.state.turnCount ?? 0,
+                    usage: {
+                        promptTokens: usage.promptTokens ?? 0,
+                        completionTokens: usage.completionTokens ?? 0,
+                        totalTokens: usage.totalTokens ?? 0,
+                    },
+                };
+            }
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
             messages.push(userMsg);
-            session.transcript.appendMessage("user", userMessageContent, { injected: options?.injected === true });
+            session.transcript.appendMessage("user", userMessageContent, {
+                injected: options?.injected === true,
+                clientMessageId: options?.clientMessageId,
+            });
             // Flush "active" status to disk immediately. resume() set it in memory
             // (session-manager.ts), but without this write the on-disk state.json
             // still shows the previous run's terminal reason — so any external
@@ -1139,13 +1209,20 @@ export class Engine {
             // Cold start: shape (2) reuses the host-supplied sid; shape (3)
             // lets sessionManager generate one with nanoid.
             session = this.sessionManager.create(cwd, this.config.llm.model, this.config.llm.provider, options?.sessionId, this.config.isSubAgent === true ? getCurrentSid() : undefined, this.config.isSubAgent === true ? "subagent" : this.config.origin);
-            messages = [{ role: "user", content: userMessageContent }];
-            session.transcript.appendMessage("user", userMessageContent);
+            const userMsg = { role: "user", content: userMessageContent };
+            claimClientMessageId(session, options?.clientMessageId, "submit");
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
+            messages = [userMsg];
+            session.transcript.appendMessage("user", userMessageContent, {
+                clientMessageId: options?.clientMessageId,
+            });
             // Save first user message as session summary — text only. The summary
             // shows up in the session list; "[image]" is more informative than a
             // truncated `[object Object]` when the prompt was purely visual.
             const summarySrc = parsedTask.hasImages
-                ? parsedTask.text || `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
+                ? parsedTask.text ||
+                    `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
                 : taskText;
             session.state.summary = summarySrc.slice(0, 80).replace(/\n/g, " ");
             this.sessionManager.saveState(session.state);
@@ -1483,26 +1560,27 @@ export class Engine {
             // run would be evaluated fresh and might get a different replacement
             // string than the one already in the message, breaking idempotency.
             contextManager.initReplacementStateFromMessages(messages);
-            // Summarization (context-compaction + tool-result summaries) are auxiliary
-            // calls — route them to the configured aux model so they don't burn the
-            // expensive primary model every turn (same rationale as runMemoryPipeline).
-            // Resolved once here (not per-call) so the magnetic-disk settings re-read
-            // in resolveAuxClient stays off the compaction hot path. Falls back to the
-            // primary client when no aux model is configured.
+            // Two summarizers with DIFFERENT quality needs:
+            //
+            // 1. Context-compaction summary (setSummarizeFn) → PRIMARY model. This
+            //    condenses many rounds into the running summary that REPLACES the real
+            //    history; a dropped decision makes the conversation "forget" and poisons
+            //    every subsequent turn. It fires only near the compact ratio (~0.85), so
+            //    it's infrequent — quality far outweighs the occasional extra cost of a
+            //    primary-model call. (Manual /compact uses the primary for the same
+            //    reason; see forceCompact.)
+            //
+            // 2. Tool-use one-liner summaries (modelFacade.summarize below) → AUX model.
+            //    These are tiny throwaway outputs ("Wrote design doc") fired every turn;
+            //    that high-frequency, low-stakes chore is exactly what aux is for.
             const auxSummaryClient = await this.resolveAuxClient(llmClient);
-            contextManager.setSummarizeFn(async (prompt) => {
-                const summaryResponse = await auxSummaryClient.createMessage({
-                    systemPrompt: "You are a conversation summarizer. Be concise and factual.",
-                    messages: [{ role: "user", content: prompt }],
-                    tools: [],
-                    maxTokens: 1024,
-                    // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
-                    // this flips thinking off (~3x faster, fewer tokens); on every other
-                    // OpenAI-compatible provider the field is ignored.
-                    reasoning: { mode: "off" },
-                });
-                return summaryResponse.text;
-            });
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCumulativeUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordCumulativeUsage));
             // Create components (requires resolved llmClient).
             const modelFacade = new ModelFacade(llmClient, session.transcript);
             // Session-cumulative usage baseline: the LLM client is recreated per run
@@ -1676,7 +1754,9 @@ export class Engine {
                     pendingCompactInfo = null;
                     return info;
                 },
-                consumeSteer: () => this.consumeSteer(sid),
+                consumeSteer: (source) => this.consumeSteer(sid, source),
+                claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+                recordCumulativeUsage,
                 // Clear the persisted goal for a self-reported completion / confirmed
                 // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
                 // turns don't re-arm) AND persists it, and drops the in-flight stop
@@ -1715,6 +1795,7 @@ export class Engine {
                 maxToolCallsPerTurn: this.config.maxToolCallsPerTurn ?? 25,
                 onStream: options?.onStream,
                 signal: options?.signal,
+                freshImageMessages: freshImageMessage ? [freshImageMessage] : undefined,
                 // Goal mode: the active goal is surfaced to the on_stop handler via
                 // ctx.data.goal; the GoalStopHook (registered above) judges it.
                 goal: normalizedGoal,
@@ -1727,16 +1808,23 @@ export class Engine {
                     // baseline + this run's running total (idempotent per boundary,
                     // accumulates across runs; carries cacheRead/cacheCreation too).
                     session.state.tokenUsage = foldRunUsage(usageBaseline, modelFacade.getUsage());
-                    // Surface the session-cumulative cache counts to the UI (the "本会话
-                    // 累计命中率" tooltip). Separate from turn-loop's per-response
-                    // usage_update (which drives the live context reading).
-                    const cum = session.state.tokenUsage;
+                    // Surface the whole-session monotonic cache counts to the UI.
+                    // Separate from turn-loop's authoritative per-response emit (which
+                    // drives the live context reading and single-turn metric).
+                    const cumulative = normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage);
+                    const cumulativeHitRate = cumulativeCacheHitRate(cumulative);
                     options?.onStream?.({
                         type: "usage_update",
-                        promptTokens: cum.promptTokens,
-                        sessionPromptTokens: cum.promptTokens,
-                        sessionCacheReadTokens: cum.cacheReadTokens ?? 0,
-                        sessionCacheCreationTokens: cum.cacheCreationTokens ?? 0,
+                        promptTokens: cumulative.cumulativePromptTokens,
+                        cumulativePromptTokens: cumulative.cumulativePromptTokens,
+                        cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                        ...(cumulativeHitRate !== undefined
+                            ? { cumulativeCacheHitRate: cumulativeHitRate }
+                            : {}),
+                        sessionPromptTokens: cumulative.cumulativePromptTokens,
+                        sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
                     });
                     if (this.config.costStore) {
                         session.state.costState = this.config.costStore.serialize();
@@ -1940,6 +2028,28 @@ export class Engine {
      * active run's client) when unset, unknown, or on any build failure — aux
      * work is best-effort and must never break a run.
      */
+    /**
+     * Build the SummarizeFn used for context compaction. Extracted so both the
+     * run path and forceCompact share one definition of the summarization call.
+     */
+    buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
+        return async (prompt) => {
+            const summaryResponse = await auxSummaryClient.createMessage({
+                systemPrompt: "You are a conversation summarizer. Be concise and factual.",
+                messages: [{ role: "user", content: prompt }],
+                tools: [],
+                maxTokens: 1024,
+                // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
+                // this flips thinking off (~3x faster, fewer tokens); on every other
+                // OpenAI-compatible provider the field is ignored.
+                reasoning: { mode: "off" },
+            });
+            if (summaryResponse.usage) {
+                recordCumulativeUsage?.(summaryResponse.usage);
+            }
+            return summaryResponse.text;
+        };
+    }
     async resolveAuxClient(fallback) {
         let auxKey;
         try {
@@ -2005,7 +2115,9 @@ export class Engine {
             // extraction, which then padded the memory store with low-signal
             // entries. 8 messages is roughly "more than a single back-and-forth"
             // — substantive enough to be worth a durable note.
-            const messages = transcript.toMessages().filter((m) => m.role === "user" || m.role === "assistant");
+            const messages = transcript
+                .toMessages()
+                .filter((m) => m.role === "user" || m.role === "assistant");
             if (messages.length < 8)
                 return;
             // Memory orchestrator + dream-loop calls are auxiliary LLM calls
@@ -2107,10 +2219,8 @@ export class Engine {
         return entry;
     }
     /**
-     * Zero a session's cumulative token/cache usage on disk. Called on a model
-     * switch: a different model has its own prompt cache, so the accumulated
-     * cache-hit stats from the prior model are no longer meaningful. The next
-     * run's baseline (snapshotted from state.tokenUsage) then starts from zero.
+     * Zero the legacy/model-scoped token/cache usage window on disk. The
+     * whole-session cumulative counters are intentionally left alone.
      */
     resetSessionUsage(sessionId) {
         const zero = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -2182,7 +2292,9 @@ export class Engine {
             try {
                 chmodSync(file, 0o600);
             }
-            catch { /* best-effort */ }
+            catch {
+                /* best-effort */
+            }
         }
         catch (err) {
             logger.warn(`persistActiveModel failed: ${err.message}`);
@@ -2254,8 +2366,14 @@ export class Engine {
             // The builtin tool SET is ctor-frozen and may be shared via runtime — we
             // do NOT rebuild it here. If the new preset implies a different builtin
             // tool set, that part of the change only lands on session restart.
-            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName }).slice().sort().join(",");
-            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name }).slice().sort().join(",");
+            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName })
+                .slice()
+                .sort()
+                .join(",");
+            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name })
+                .slice()
+                .sort()
+                .join(",");
             if (prevTools !== nextTools) {
                 logger.warn("engine.preset_reload.tool_set_change_needs_restart", {
                     from: prevPresetName,
@@ -2351,25 +2469,74 @@ export class Engine {
         }
     }
     /**
-     * Force context compaction on the current session.
+     * Force context compaction on a session.
      * Returns token stats before/after.
      */
-    forceCompact() {
-        const sessionId = this.lastSessionId;
-        if (!this.lastContextManager || !sessionId) {
+    async forceCompact(sessionId) {
+        const effectiveSessionId = sessionId ?? this.lastSessionId;
+        if (!effectiveSessionId) {
             return { before: 0, after: 0, strategy: "none (no active session)" };
         }
-        const sourceMessages = this.compactedMessagesBySession.get(sessionId) ??
-            this.sessionManager.resume(sessionId).transcript.toMessages();
+        const session = this.sessionManager.resume(effectiveSessionId);
+        const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ?? session.transcript.toMessages();
         const before = estimateTokens(sourceMessages);
-        const compacted = this.lastContextManager.manage(sourceMessages);
+        let contextManager = this.lastContextManager;
+        if (!contextManager || this.lastSessionId !== effectiveSessionId) {
+            contextManager = new ContextManager({
+                maxTokens: this.resolveMaxContextTokens(),
+                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
+            });
+            contextManager.setTranscriptPath(session.transcript.getFilePath());
+            contextManager.initReplacementStateFromMessages(sourceMessages);
+            this.lastContextManager = contextManager;
+        }
+        // Manual /compact emits its UI boundary at the protocol layer from the
+        // final before/after result. Capture the tier here, but avoid reusing a
+        // stale run callback retained on lastContextManager, which could otherwise
+        // double-emit.
+        let compactStrategy;
+        contextManager.setOnCompact((info) => {
+            if (info.after < info.before)
+                compactStrategy = info.strategy;
+        });
+        // Manual /compact = maximum compaction NOW. The automatic ladder waits for
+        // compactAtRatio (0.85 * window), so on a 1M-window model an 800k text-only
+        // conversation sits under the gate and manage() only runs a no-op micro.
+        // Wire a summarizeFn (the run path does this per-run; a cold forceCompact on
+        // a resumed-but-never-run session has none) and call forceSummarize, which
+        // ignores the ratio gate and always summarizes (falling back to snip/window).
+        //
+        // Use the PRIMARY model, not the aux model. Automatic background compaction
+        // routes to aux to keep the high-frequency path cheap, but summarization is
+        // a high-fidelity task (drop a decision and the conversation "forgets"), and
+        // a manual /compact is a low-frequency, user-initiated request for quality.
+        // The aux model is sized for tiny outputs (titles, memory extraction), so
+        // downgrading the one compaction the user explicitly asked for is backwards.
+        try {
+            const primaryClient = await createLLMClient(this.config.llm, this.config.clientDefaults);
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCompactUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                this.sessionManager.saveState(session.state);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(primaryClient, recordCompactUsage));
+        }
+        catch (err) {
+            logger.warn("engine.force_compact_client_failed", {
+                error: err.message,
+            });
+        }
+        const compacted = await contextManager.forceSummarize(sourceMessages);
         const after = estimateTokens(compacted);
-        this.compactedMessagesBySession.set(sessionId, compacted);
+        this.compactedMessagesBySession.set(effectiveSessionId, compacted);
+        this.lastSessionId = effectiveSessionId;
         this.lastMessages = compacted;
         return {
             before,
             after,
-            strategy: before === after ? "no compaction needed" : "compacted",
+            strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
         };
     }
     stripUserContextMessage(messages, userContextMsg) {
@@ -2463,7 +2630,11 @@ export class Engine {
                 backend = interactive;
             }
             else {
-                backend = new HeadlessApprovalBackend(mode === "bypassPermissions" ? "approve-all" : mode === "dontAsk" ? "deny-all" : "deny-all");
+                backend = new HeadlessApprovalBackend(mode === "bypassPermissions"
+                    ? "approve-all"
+                    : mode === "dontAsk"
+                        ? "deny-all"
+                        : "deny-all");
             }
         }
         return { rules, backend };
@@ -2505,7 +2676,8 @@ export class Engine {
      * rule set buildPermissionConfig does, without constructing a backend.
      */
     getPermissionRules() {
-        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd()).rules;
+        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd())
+            .rules;
     }
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
@@ -2592,12 +2764,8 @@ export class Engine {
     getAgentDefinitions(cwd) {
         const disabledAgents = this.readDisabledAgents(cwd);
         const disabledPlugins = this.readDisabledLists().disabledPlugins;
-        const disabledKey = [...disabledAgents, "::", ...disabledPlugins]
-            .slice()
-            .sort()
-            .join(" ");
-        if (this.agentDefsCache?.cwd !== cwd ||
-            this.agentDefsCache.disabledKey !== disabledKey) {
+        const disabledKey = [...disabledAgents, "::", ...disabledPlugins].slice().sort().join(" ");
+        if (this.agentDefsCache?.cwd !== cwd || this.agentDefsCache.disabledKey !== disabledKey) {
             this.agentDefsCache = {
                 cwd,
                 disabledKey,

package/dist/engine/model-facade.js

@@ -5,6 +5,7 @@ import { logger, getCurrentSid } from "../logging/logger.js";
 import { recordLLMError, recordLLMRequest, recordLLMResponse, } from "../logging/session-recorder.js";
 import { sanitizeMessages } from "../logging/sanitize-messages.js";
 import { addAPIDuration, addToModelUsage, addInputTokens, addOutputTokens } from "../state.js";
+import { cacheHitRateFromUsage } from "./session-usage.js";
 let _reqSeq = 0;
 function nextReqId() {
     _reqSeq += 1;
@@ -20,18 +21,7 @@ function nextReqId() {
  * any caching tuning (docs/todo/prompt-cache-optimization.md §四 step 1).
  */
 export function cacheHitRate(usage) {
-    if (!usage)
-        return undefined;
-    const read = usage.cacheReadTokens ?? 0;
-    const creation = usage.cacheCreationTokens ?? 0;
-    if (read === 0 && creation === 0)
-        return undefined;
-    const prompt = usage.promptTokens ?? 0;
-    const uncached = Math.max(0, prompt - read - creation);
-    const denom = read + creation + uncached;
-    if (denom === 0)
-        return undefined;
-    return read / denom;
+    return cacheHitRateFromUsage(usage);
 }
 export class ModelFacade {
     client;

package/dist/engine/query.js

@@ -9,6 +9,7 @@
  */
 import { TurnLoop } from "./turn-loop.js";
 import { logger } from "../logging/logger.js";
+import { messageHasBase64ImagePayload } from "../context/compaction.js";
 // ─── Query generator ────────────────────────────────────────────────
 /**
  * Run an agentic query and yield stream events as they occur.
@@ -37,6 +38,7 @@ export async function* query(params) {
         maxToolCallsPerTurn,
         onStream,
         signal,
+        freshImageMessages: messages.filter(messageHasBase64ImagePayload),
     };
     // Local overhead store — query() is a standalone entry point without a real
     // session id, so per-call in-memory state is enough.

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.