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

package/dist/context/compaction.d.ts

@@ -16,6 +16,35 @@ import type { Message } from "../types.js";
  * Uses per-block-type estimation with 33% overhead padding.
  */
 export declare function estimateTokens(messages: Message[]): number;
+export declare const IMAGE_HISTORY_PLACEHOLDER_PREFIX = "[image #";
+export declare const IMAGE_HISTORY_PLACEHOLDER_SUFFIX = ", \u5DF2\u5904\u7406 / already provided earlier]";
+interface ImagePreserveSet {
+    has(message: Message): boolean;
+}
+export interface DowngradeImageHistoryOptions {
+    /**
+     * Messages whose image payloads are being sent for their first model
+     * consumption in this request. They still count toward image numbering but
+     * keep their base64 until the caller clears the preserve set after a
+     * successful model response.
+     */
+    preserveMessages?: ImagePreserveSet;
+}
+export interface DowngradeImageHistoryResult {
+    messages: Message[];
+    replacedCount: number;
+}
+/**
+ * Replace already-consumed image payload blocks with compact text markers.
+ *
+ * The transcript may retain the full image bytes for rendering/resume, but the
+ * working message history sent to the model should not re-send base64 after the
+ * model has seen it once. This handles both our internal Anthropic-style image
+ * blocks and OpenAI-style data-url image blocks defensively, including images
+ * nested inside tool_result.content arrays (view_image / browser screenshots).
+ */
+export declare function downgradeImagePayloadsInHistory(messages: Message[], options?: DowngradeImageHistoryOptions): DowngradeImageHistoryResult;
+export declare function messageHasBase64ImagePayload(message: Message): boolean;
 /**
  * Reconcile user-supplied compaction ratios into a safe ordering.
  *
@@ -170,3 +199,4 @@ export declare function dropOldestRounds(messages: Message[], roundsToDrop: numb
  * messages. Returns paths only — the model uses Read tool on demand.
  */
 export declare function extractReferencedFilePaths(messages: Message[]): string[];
+export {};

package/dist/context/compaction.js

@@ -18,6 +18,99 @@ import { estimateMessagesTokens } from "./token-counter.js";
 export function estimateTokens(messages) {
     return Math.ceil(estimateMessagesTokens(messages) * (4 / 3));
 }
+export const IMAGE_HISTORY_PLACEHOLDER_PREFIX = "[image #";
+export const IMAGE_HISTORY_PLACEHOLDER_SUFFIX = ", 已处理 / already provided earlier]";
+/**
+ * Replace already-consumed image payload blocks with compact text markers.
+ *
+ * The transcript may retain the full image bytes for rendering/resume, but the
+ * working message history sent to the model should not re-send base64 after the
+ * model has seen it once. This handles both our internal Anthropic-style image
+ * blocks and OpenAI-style data-url image blocks defensively, including images
+ * nested inside tool_result.content arrays (view_image / browser screenshots).
+ */
+export function downgradeImagePayloadsInHistory(messages, options = {}) {
+    let nextImageNumber = 1;
+    let replacedCount = 0;
+    let changed = false;
+    const placeholderFor = (imageNumber) => ({
+        type: "text",
+        text: `${IMAGE_HISTORY_PLACEHOLDER_PREFIX}${imageNumber}${IMAGE_HISTORY_PLACEHOLDER_SUFFIX}`,
+    });
+    const transformBlocks = (blocks, preserve) => {
+        let blocksChanged = false;
+        const out = blocks.map((block) => {
+            const placeholderNumber = imageHistoryPlaceholderNumber(block);
+            if (placeholderNumber !== undefined) {
+                nextImageNumber = Math.max(nextImageNumber, placeholderNumber + 1);
+                return block;
+            }
+            if (isBase64ImageBlock(block)) {
+                const imageNumber = nextImageNumber++;
+                if (preserve)
+                    return block;
+                replacedCount++;
+                blocksChanged = true;
+                return placeholderFor(imageNumber);
+            }
+            if (block.type === "tool_result" && Array.isArray(block.content)) {
+                const nested = transformBlocks(block.content, preserve);
+                if (nested.changed) {
+                    blocksChanged = true;
+                    return { ...block, content: nested.blocks };
+                }
+            }
+            return block;
+        });
+        return { blocks: blocksChanged ? out : blocks, changed: blocksChanged };
+    };
+    const out = messages.map((msg) => {
+        if (!Array.isArray(msg.content))
+            return msg;
+        const preserve = options.preserveMessages?.has(msg) === true;
+        const result = transformBlocks(msg.content, preserve);
+        if (!result.changed)
+            return msg;
+        changed = true;
+        return { ...msg, content: result.blocks };
+    });
+    return { messages: changed ? out : messages, replacedCount };
+}
+export function messageHasBase64ImagePayload(message) {
+    if (!Array.isArray(message.content))
+        return false;
+    return message.content.some(blockHasBase64ImagePayload);
+}
+function blockHasBase64ImagePayload(block) {
+    if (isBase64ImageBlock(block))
+        return true;
+    return (block.type === "tool_result" &&
+        Array.isArray(block.content) &&
+        block.content.some(blockHasBase64ImagePayload));
+}
+function imageHistoryPlaceholderNumber(block) {
+    if (block.type !== "text" || typeof block.text !== "string")
+        return undefined;
+    const escapedPrefix = IMAGE_HISTORY_PLACEHOLDER_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escapedSuffix = IMAGE_HISTORY_PLACEHOLDER_SUFFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = block.text.match(new RegExp(`^${escapedPrefix}(\\d+)${escapedSuffix}$`));
+    if (!match?.[1])
+        return undefined;
+    const n = Number(match[1]);
+    return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+function isBase64ImageBlock(block) {
+    if (block.type === "image" &&
+        block.source?.type === "base64" &&
+        typeof block.source.data === "string" &&
+        block.source.data.length > 0) {
+        return true;
+    }
+    const maybeOpenAI = block;
+    return (maybeOpenAI.type === "image_url" &&
+        typeof maybeOpenAI.image_url?.url === "string" &&
+        /^data:image\/[^;,]+;base64,/i.test(maybeOpenAI.image_url.url));
+}
 /**
  * Reconcile user-supplied compaction ratios into a safe ordering.
  *

package/dist/context/manager.d.ts

@@ -41,6 +41,8 @@ export declare class ContextManager {
     private config;
     private summarizeFn;
     private consecutiveSummaryFailures;
+    /** Prevents repeated spin-band LLM calls after a summary generated no shrink. */
+    private suppressNoOpMicroSummaryUntilCompact;
     private lastSummary;
     /** Last known actual token count from API usage data. */
     private lastActualTokens;
@@ -73,6 +75,7 @@ export declare class ContextManager {
      * Set the summarize function (injected by Engine).
      */
     setSummarizeFn(fn: SummarizeFn): void;
+    private trySummaryCompact;
     /**
      * Set the transcript path so compaction can reference it. The
      * tool-results directory lives alongside the transcript file:
@@ -97,6 +100,21 @@ export declare class ContextManager {
      * Call this when you have access to the LLM (between turns).
      */
     manageAsync(messages: Message[]): Promise<Message[]>;
+    /**
+     * Force maximum compaction, ignoring the ratio gates. This is what a manual
+     * `/compact` invokes: the user explicitly asked to shrink NOW, so we don't
+     * wait for the prompt to reach compactAtRatio.
+     *
+     * Order: tier-0 cleanups (persist/truncate/dedupe/mask) + microcompact, then
+     * an unconditional LLM summary of the older messages. If no summarizeFn is
+     * wired (or it fails / yields nothing), fall back to snip → window so the
+     * call still shrinks the conversation rather than no-opping.
+     *
+     * Unlike manage()/manageAsync(), there is NO `ratio >= compactAtRatio` gate:
+     * a long-but-under-threshold text-only conversation (the /compact bug) still
+     * gets summarized here.
+     */
+    forceSummarize(messages: Message[]): Promise<Message[]>;
     /**
      * Persist large tool_result blocks to disk and replace them with a
      * preview + filepath. No-op when transcript path hasn't been set

package/dist/context/manager.js

@@ -41,6 +41,8 @@ export class ContextManager {
     config;
     summarizeFn;
     consecutiveSummaryFailures = 0;
+    /** Prevents repeated spin-band LLM calls after a summary generated no shrink. */
+    suppressNoOpMicroSummaryUntilCompact = false;
     lastSummary;
     /** Last known actual token count from API usage data. */
     lastActualTokens;
@@ -91,6 +93,64 @@ export class ContextManager {
     setSummarizeFn(fn) {
         this.summarizeFn = fn;
     }
+    async trySummaryCompact(messages, before, logEvent) {
+        if (!this.summarizeFn || this.consecutiveSummaryFailures >= 3) {
+            return { messages, tokens: before, compacted: false, noProgress: false };
+        }
+        try {
+            const keepRecentN = Math.max(8, Math.floor(messages.length * 0.3));
+            const messagesToSummarize = messages.slice(1, -keepRecentN); // skip first (userContext) and recent
+            if (messagesToSummarize.length <= 3) {
+                return { messages, tokens: before, compacted: false, noProgress: false };
+            }
+            // Rolling summary: if a prior summary is already anchored in the
+            // messages (from an earlier compaction in this session or in a resumed
+            // session), feed it back so the LLM merges-updates rather than
+            // re-summarizes from scratch.
+            const priorSummary = extractAnchoredSummary(messages) ?? this.lastSummary;
+            const prompt = buildSummarizationPrompt(messagesToSummarize, priorSummary);
+            const summary = await this.summarizeFn(prompt);
+            if (!summary || summary.length <= 50) {
+                this.consecutiveSummaryFailures++;
+                logger.warn("context.summary_failed", {
+                    failures: this.consecutiveSummaryFailures,
+                    error: "summary was empty or too short",
+                });
+                return { messages, tokens: before, compacted: false, noProgress: true };
+            }
+            const compacted = applySummaryCompaction(messages, summary, keepRecentN, this.transcriptPath);
+            const after = estimateTokens(compacted);
+            if (after >= before) {
+                this.consecutiveSummaryFailures++;
+                logger.warn("context.summary_no_progress", {
+                    failures: this.consecutiveSummaryFailures,
+                    before,
+                    after,
+                    summaryLen: summary.length,
+                    rolling: priorSummary !== undefined,
+                });
+                return { messages, tokens: before, compacted: false, noProgress: true };
+            }
+            this.consecutiveSummaryFailures = 0;
+            this.lastSummary = summary;
+            logger.info(logEvent, {
+                before,
+                after,
+                summaryLen: summary.length,
+                rolling: priorSummary !== undefined,
+            });
+            this.onCompact?.({ strategy: "summary", before, after });
+            return { messages: compacted, tokens: after, compacted: true, noProgress: false };
+        }
+        catch (err) {
+            this.consecutiveSummaryFailures++;
+            logger.warn("context.summary_failed", {
+                failures: this.consecutiveSummaryFailures,
+                error: err.message,
+            });
+            return { messages, tokens: before, compacted: false, noProgress: false };
+        }
+    }
     /**
      * Set the transcript path so compaction can reference it. The
      * tool-results directory lives alongside the transcript file:
@@ -240,7 +300,9 @@ export class ContextManager {
         result = applyToolResultBudget(result);
         // Tier 1: microcompact — see manage() for the rationale on the floor.
         const preTier1Tokens = this.estimateTokensHybrid(result);
-        if (preTier1Tokens > this.config.maxTokens * this.config.microcompactFloorRatio) {
+        const microFloorGate = this.config.maxTokens * this.config.microcompactFloorRatio;
+        let microNoOpAtFloor = false;
+        if (preTier1Tokens > microFloorGate) {
             const keepRecentN = this.config.microcompactKeepRecent ?? defaultKeepRecent(this.config.maxTokens);
             // See manage(): onClear fires synchronously before microcompact returns,
             // so defer the token re-estimate until result is reassigned.
@@ -251,63 +313,58 @@ export class ContextManager {
                     clearedInfo = info;
                 },
             });
+            const postTier1Tokens = this.estimateTokensHybrid(result);
+            microNoOpAtFloor = postTier1Tokens === preTier1Tokens;
+            if (postTier1Tokens < preTier1Tokens) {
+                this.suppressNoOpMicroSummaryUntilCompact = false;
+            }
             if (clearedInfo) {
-                const after = this.estimateTokensHybrid(result);
                 logger.info("context.microcompact", {
                     before: preTier1Tokens,
-                    after,
+                    after: postTier1Tokens,
                     keepRecentN,
                     clearedRounds: clearedInfo.clearedRounds,
                     toolNames: clearedInfo.toolNames,
                 });
-                this.onCompact?.({ strategy: "micro", before: preTier1Tokens, after });
+                this.onCompact?.({
+                    strategy: "micro",
+                    before: preTier1Tokens,
+                    after: postTier1Tokens,
+                });
             }
         }
-        const tokens = this.estimateTokensHybrid(result);
+        let tokens = this.estimateTokensHybrid(result);
         const ratio = tokens / this.config.maxTokens;
-        // Tier 2: LLM summary if approaching limit
-        if (ratio >= this.config.compactAtRatio &&
-            this.summarizeFn &&
-            this.consecutiveSummaryFailures < 3) {
-            try {
-                const keepRecentN = Math.max(8, Math.floor(result.length * 0.3));
-                const messagesToSummarize = result.slice(1, -keepRecentN); // skip first (userContext) and recent
-                if (messagesToSummarize.length > 3) {
-                    // Rolling summary: if a prior summary is already anchored in the
-                    // messages (from an earlier compaction in this session or in a
-                    // resumed session), feed it back so the LLM merges-updates rather
-                    // than re-summarizes from scratch — preserves info that would
-                    // otherwise erode across successive compactions.
-                    const priorSummary = extractAnchoredSummary(result) ?? this.lastSummary;
-                    const prompt = buildSummarizationPrompt(messagesToSummarize, priorSummary);
-                    const summary = await this.summarizeFn(prompt);
-                    if (summary && summary.length > 50) {
-                        result = applySummaryCompaction(result, summary, keepRecentN, this.transcriptPath);
-                        this.consecutiveSummaryFailures = 0;
-                        this.lastSummary = summary;
-                        const after = estimateTokens(result);
-                        logger.info("context.summary_compact", {
-                            before: tokens,
-                            after,
-                            summaryLen: summary.length,
-                            rolling: priorSummary !== undefined,
-                        });
-                        this.onCompact?.({ strategy: "summary", before: tokens, after });
-                        return result;
-                    }
-                }
+        if (ratio < this.config.microcompactFloorRatio) {
+            this.suppressNoOpMicroSummaryUntilCompact = false;
+        }
+        const noOpMicroSpinBand = microNoOpAtFloor &&
+            ratio >= this.config.microcompactFloorRatio &&
+            ratio < this.config.compactAtRatio;
+        const shouldEscalateNoOpMicro = noOpMicroSpinBand && !this.suppressNoOpMicroSummaryUntilCompact;
+        // Tier 2: LLM summary if approaching limit, or if micro was the only tier
+        // available in the 0.70-0.85 band and it freed nothing.
+        if (ratio >= this.config.compactAtRatio || shouldEscalateNoOpMicro) {
+            const summarized = await this.trySummaryCompact(result, tokens, "context.summary_compact");
+            result = summarized.messages;
+            tokens = summarized.tokens;
+            if (summarized.compacted) {
+                this.suppressNoOpMicroSummaryUntilCompact = false;
+                return result;
             }
-            catch (err) {
-                this.consecutiveSummaryFailures++;
-                logger.warn("context.summary_failed", {
-                    failures: this.consecutiveSummaryFailures,
-                    error: err.message,
+            if (shouldEscalateNoOpMicro && summarized.noProgress) {
+                this.suppressNoOpMicroSummaryUntilCompact = true;
+                logger.info("context.micro_noop_summary_suppressed", {
+                    tokens,
+                    ratio,
+                    compactAtRatio: this.config.compactAtRatio,
+                    microcompactFloorRatio: this.config.microcompactFloorRatio,
                 });
             }
         }
-        // Reuse the `tokens` we already computed above. We only get here if the
-        // LLM summary path didn't fire (no summarizeFn, too many failures, or it
-        // threw) — fall back to the same severity ladder as manage().
+        // Reuse the `tokens` we already computed above. We only get here if no
+        // summary compacted the prompt (no summarizeFn, too many failures, a
+        // thrown error, or a generated summary that did not shrink anything).
         let live = tokens;
         const snipGate = this.config.maxTokens * this.config.compactAtRatio;
         const windowGate = this.config.maxTokens * (this.config.compactAtRatio + 0.05);
@@ -336,6 +393,61 @@ export class ContextManager {
         }
         return result;
     }
+    /**
+     * Force maximum compaction, ignoring the ratio gates. This is what a manual
+     * `/compact` invokes: the user explicitly asked to shrink NOW, so we don't
+     * wait for the prompt to reach compactAtRatio.
+     *
+     * Order: tier-0 cleanups (persist/truncate/dedupe/mask) + microcompact, then
+     * an unconditional LLM summary of the older messages. If no summarizeFn is
+     * wired (or it fails / yields nothing), fall back to snip → window so the
+     * call still shrinks the conversation rather than no-opping.
+     *
+     * Unlike manage()/manageAsync(), there is NO `ratio >= compactAtRatio` gate:
+     * a long-but-under-threshold text-only conversation (the /compact bug) still
+     * gets summarized here.
+     */
+    async forceSummarize(messages) {
+        let result = messages;
+        // Tier 0: same waste-removal + micro as the automatic path.
+        result = this.persistLargeToolResults(result);
+        result = this.truncateToolResults(result);
+        result = applyToolResultBudget(result);
+        const dedup = dedupeFileReads(result);
+        if (dedup.clearedCount > 0)
+            result = dedup.messages;
+        const masked = maskOldObservations(result);
+        if (masked.maskedCount > 0)
+            result = masked.messages;
+        const keepRecentN = this.config.microcompactKeepRecent ?? defaultKeepRecent(this.config.maxTokens);
+        result = microcompact(result, { keepRecentN });
+        let tokens = this.estimateTokensHybrid(result);
+        // Unconditional LLM summary (no ratio gate).
+        {
+            const summarized = await this.trySummaryCompact(result, tokens, "context.force_summary_compact");
+            result = summarized.messages;
+            tokens = summarized.tokens;
+            if (summarized.compacted)
+                return result;
+        }
+        // Fallback: no summary available — snip, then window, so /compact still
+        // shrinks the conversation instead of no-opping.
+        {
+            const before = tokens;
+            result = snipCompact(result, 3, 8);
+            tokens = this.estimateTokensHybrid(result);
+            if (tokens < before)
+                this.onCompact?.({ strategy: "snip", before, after: tokens });
+        }
+        if (this.estimateTokensHybrid(result) >= this.estimateTokensHybrid(messages)) {
+            const before = tokens;
+            const keepN = Math.max(10, Math.floor(result.length * 0.4));
+            result = windowCompact(result, keepN);
+            tokens = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "window", before, after: tokens });
+        }
+        return result;
+    }
     /**
      * Persist large tool_result blocks to disk and replace them with a
      * preview + filepath. No-op when transcript path hasn't been set

package/dist/context/token-counter.js

@@ -69,11 +69,24 @@ function estimateBlockTokens(block) {
     if (block.content && typeof block.content === "string") {
         tokens += estimateStringTokens(block.content);
     }
+    else if (Array.isArray(block.content)) {
+        for (const nested of block.content) {
+            tokens += estimateBlockTokens(nested);
+        }
+    }
     if (block.input) {
         tokens += estimateStringTokens(JSON.stringify(block.input));
     }
     if (block.name)
         tokens += estimateStringTokens(block.name);
+    if (block.source?.data) {
+        tokens += estimateStringTokens(block.source.media_type);
+        tokens += estimateStringTokens(block.source.data);
+    }
+    const maybeOpenAI = block;
+    if (typeof maybeOpenAI.image_url?.url === "string") {
+        tokens += estimateStringTokens(maybeOpenAI.image_url.url);
+    }
     return tokens;
 }
 export function calculateContextUsage(messages, systemPrompt, maxTokens) {

package/dist/engine/engine.d.ts

@@ -6,6 +6,7 @@ import { ToolRegistry } from "../tool-system/registry.js";
 import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
 import { HookRegistry } from "../hooks/registry.js";
 import { type GoalConfig, type GoalExtension } from "./goal.js";
+import { type CompactStrategy } from "../context/manager.js";
 import { SessionManager } from "../session/session-manager.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 import type { CapabilityOverride } from "../settings/schema.js";
@@ -27,6 +28,10 @@ export declare function compatFileNamesFrom(instructions?: {
 }): string[];
 export type { EngineConfig, EngineHookConfig, EngineResult } from "./types.js";
 import type { EngineConfig, EngineResult } from "./types.js";
+export interface EnqueueSteerResult {
+    accepted: boolean;
+    id: string;
+}
 export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
@@ -260,16 +265,16 @@ export declare 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: string, text: string, id?: string): void;
+    enqueueSteer(sessionId: string, text: string, id?: string, clientMessageId?: string): EnqueueSteerResult;
     /**
      * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
      * removed, false if it was already consumed by the turn loop (can't take it
@@ -318,6 +323,8 @@ export declare class Engine {
          * on replay (matching the live UI, which shows only the assistant reply).
          */
         injected?: boolean;
+        /** Stable id for this user-intent, used to make duplicate submits idempotent. */
+        clientMessageId?: string;
     }): Promise<EngineResult>;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
@@ -332,6 +339,11 @@ export declare 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.
+     */
+    private buildSummarizeFn;
     private resolveAuxClient;
     private runMemoryPipeline;
     /**
@@ -363,10 +375,8 @@ export declare class Engine {
      */
     switchModel(key: string): ModelEntry;
     /**
-     * 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: string): void;
     /**
@@ -452,14 +462,14 @@ export declare class Engine {
     clearGoal(sessionId: string): boolean;
     injectContext(sessionId: string, content: string): void;
     /**
-     * Force context compaction on the current session.
+     * Force context compaction on a session.
      * Returns token stats before/after.
      */
-    forceCompact(): {
+    forceCompact(sessionId?: string): Promise<{
         before: number;
         after: number;
-        strategy: string;
-    };
+        strategy: "none (no active session)" | "no compaction needed" | "compacted" | CompactStrategy;
+    }>;
     private stripUserContextMessage;
     private getSettingsManager;
     /**