@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/context/manager.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Context manager — three-tier context management.
+ *
+ * Tier 1: microcompact (sync, zero-cost) — clear old tool_result content
+ * Tier 2: LLM summary (async) — generate summary of older messages via model call
+ * Tier 3: window compact (sync, emergency) — aggressive truncation fallback
+ */
+import type { Message } from "../types.js";
+export interface ContextManagerConfig {
+    maxTokens: number;
+    compactAtRatio: number;
+    summarizeAtRatio: number;
+    maxToolResultChars: number;
+    /**
+     * Lower bound, as a ratio of maxTokens, below which microcompact will not
+     * run. CC's external (non-cache-edit) path is "autocompact handles context
+     * pressure"; mirror that by leaving early-turn context alone so a model
+     * with a 1M window doesn't see its first-3-rounds Read results wiped at
+     * 23k tokens. Raising the floor also keeps prompt-cache prefixes warm in
+     * short sessions.
+     */
+    microcompactFloorRatio: number;
+    /**
+     * Most-recent compactable rounds microcompact keeps untouched. Auto-derived
+     * from maxTokens when not set explicitly: bigger window → keep more.
+     */
+    microcompactKeepRecent?: number;
+}
+/**
+ * Async function type for LLM summarization calls.
+ * Injected by the Engine so the ContextManager doesn't depend on LLM directly.
+ */
+export type SummarizeFn = (prompt: string) => Promise<string>;
+export type CompactStrategy = "micro" | "summary" | "window" | "snip" | "emergency";
+export type OnCompactFn = (info: {
+    strategy: CompactStrategy;
+    before: number;
+    after: number;
+}) => void;
+export declare class ContextManager {
+    private config;
+    private toolCallHashes;
+    private summarizeFn;
+    private consecutiveSummaryFailures;
+    private lastSummary;
+    /** Last known actual token count from API usage data. */
+    private lastActualTokens;
+    /** Message count at the time lastActualTokens was recorded. */
+    private lastActualAtMessageCount;
+    /** Path to session transcript — passed to summary compaction for on-demand access. */
+    private transcriptPath;
+    /** Notified whenever any compaction tier fires, including microcompact. */
+    private onCompact;
+    /**
+     * Tool-result persistence state. Created lazily once we know where to
+     * write files (i.e. once setTranscriptPath has been called).
+     * `null` = persistence has been explicitly disabled.
+     */
+    private replacementState;
+    private toolResultsDir;
+    constructor(config?: Partial<ContextManagerConfig>);
+    setOnCompact(fn: OnCompactFn): void;
+    /**
+     * Record actual token usage from API response.
+     * Used for hybrid estimation: actual + estimate for new messages.
+     */
+    recordActualUsage(inputTokens: number, messageCount: number): void;
+    /**
+     * Best-effort token estimate: uses actual API usage as base if available,
+     * plus estimation for messages added since the last API call.
+     */
+    private estimateTokensHybrid;
+    /**
+     * Set the summarize function (injected by Engine).
+     */
+    setSummarizeFn(fn: SummarizeFn): void;
+    /**
+     * Set the transcript path so compaction can reference it. The
+     * tool-results directory lives alongside the transcript file:
+     *   <transcriptDir>/tool-results/<toolUseId>.txt
+     */
+    setTranscriptPath(path: string): void;
+    /**
+     * Initialize tool-result-persistence state from already-loaded messages.
+     * Call this once per session, after setTranscriptPath, when resuming so
+     * the manager re-enters the same "frozen decision" state it had on the
+     * previous run. Without this, a resumed session would re-evaluate
+     * every result against the current threshold and might flip choices.
+     */
+    initReplacementStateFromMessages(messages: Message[]): void;
+    /**
+     * Apply progressive context management (sync path).
+     * For Tier 2 (LLM summary), call manageAsync instead.
+     */
+    manage(messages: Message[]): Message[];
+    /**
+     * Async context management — attempts LLM summarization before falling back.
+     * Call this when you have access to the LLM (between turns).
+     */
+    manageAsync(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
+     * (e.g. unit tests that exercise compaction directly without a session).
+     */
+    private persistLargeToolResults;
+    /**
+     * Truncate oversized tool results in messages.
+     */
+    private truncateToolResults;
+    /**
+     * Reactive compaction check — call during streaming to detect if
+     * token usage is approaching the limit mid-turn.
+     * Returns true if emergency compaction should be triggered.
+     */
+    shouldReactiveCompact(messages: Message[], currentResponseTokens: number): boolean;
+    /**
+     * Check if context is approaching limits.
+     */
+    checkLimits(messages: Message[]): {
+        tokens: number;
+        ratio: number;
+        needsCompact: boolean;
+        needsEmergency: boolean;
+    };
+    /**
+     * Deduplicate tool calls by hashing arguments.
+     */
+    deduplicateToolCalls(calls: Array<{
+        toolName: string;
+        args: Record<string, unknown>;
+    }>): {
+        toExecute: typeof calls;
+        cached: Array<{
+            toolName: string;
+            args: Record<string, unknown>;
+            result: string;
+        }>;
+    };
+    /**
+     * Record a tool call result for dedup tracking.
+     */
+    recordToolResult(toolName: string, args: Record<string, unknown>, result: string): void;
+    private hashCall;
+}

package/dist/context/manager.js

@@ -0,0 +1,423 @@
+/**
+ * Context manager — three-tier context management.
+ *
+ * Tier 1: microcompact (sync, zero-cost) — clear old tool_result content
+ * Tier 2: LLM summary (async) — generate summary of older messages via model call
+ * Tier 3: window compact (sync, emergency) — aggressive truncation fallback
+ */
+import { estimateTokens, microcompact, snipCompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, applyToolResultBudget, extractAnchoredSummary, } from "./compaction.js";
+import { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, } from "./tool-result-storage.js";
+import { logger } from "../logging/logger.js";
+const DEFAULT_CONFIG = {
+    // 0.85 ≈ effectiveContextWindow − reserved-output buffer (CC's
+    // autoCompactThreshold pattern: window − 13k buffer − 20k output budget
+    // ≈ 0.83 on a 200k window, 0.97 on 1M). 0.6 was wasting 40% of any model
+    // with a window over ~150k.
+    maxTokens: 200_000,
+    compactAtRatio: 0.85,
+    summarizeAtRatio: 0.92,
+    maxToolResultChars: 30_000,
+    // 0.7 leaves micro idle until the prompt is ~70% full. Below this we
+    // let tool_results stay intact: under-pressure context doesn't need
+    // micro and wiping early Read/Bash output just forces the model to
+    // re-fetch the same files later. CC's external path triggers around
+    // 70-75% of the window; this matches it. Was 0.5 — on a 200k model
+    // that fired at 100k where a long-but-not-overloaded conversation
+    // (~130k tokens) tripped micro every single turn, with the cleared
+    // 8 rounds promptly replaced by 5 fresh ones so the next turn was
+    // back at 130k and the cycle repeated. 0.7 → 140k floor, leaving
+    // realistic headroom before we start churning.
+    microcompactFloorRatio: 0.7,
+};
+/**
+ * Default keepRecent for microcompact, scaled to the model's context window.
+ * Mirrors CC's "keep recent 5" baseline but lets a 1M-window model retain
+ * proportionally more tool_result detail before clearing kicks in.
+ */
+function defaultKeepRecent(maxTokens) {
+    return Math.max(5, Math.floor(maxTokens / 100_000));
+}
+export class ContextManager {
+    config;
+    toolCallHashes = new Map();
+    summarizeFn;
+    consecutiveSummaryFailures = 0;
+    lastSummary;
+    /** Last known actual token count from API usage data. */
+    lastActualTokens;
+    /** Message count at the time lastActualTokens was recorded. */
+    lastActualAtMessageCount;
+    /** Path to session transcript — passed to summary compaction for on-demand access. */
+    transcriptPath;
+    /** Notified whenever any compaction tier fires, including microcompact. */
+    onCompact;
+    /**
+     * Tool-result persistence state. Created lazily once we know where to
+     * write files (i.e. once setTranscriptPath has been called).
+     * `null` = persistence has been explicitly disabled.
+     */
+    replacementState;
+    toolResultsDir;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    setOnCompact(fn) {
+        this.onCompact = fn;
+    }
+    /**
+     * Record actual token usage from API response.
+     * Used for hybrid estimation: actual + estimate for new messages.
+     */
+    recordActualUsage(inputTokens, messageCount) {
+        this.lastActualTokens = inputTokens;
+        this.lastActualAtMessageCount = messageCount;
+    }
+    /**
+     * Best-effort token estimate: uses actual API usage as base if available,
+     * plus estimation for messages added since the last API call.
+     */
+    estimateTokensHybrid(messages) {
+        if (this.lastActualTokens !== undefined &&
+            this.lastActualAtMessageCount !== undefined &&
+            this.lastActualAtMessageCount < messages.length) {
+            const newMessages = messages.slice(this.lastActualAtMessageCount);
+            const newTokens = estimateTokens(newMessages);
+            return this.lastActualTokens + newTokens;
+        }
+        return estimateTokens(messages);
+    }
+    /**
+     * Set the summarize function (injected by Engine).
+     */
+    setSummarizeFn(fn) {
+        this.summarizeFn = fn;
+    }
+    /**
+     * Set the transcript path so compaction can reference it. The
+     * tool-results directory lives alongside the transcript file:
+     *   <transcriptDir>/tool-results/<toolUseId>.txt
+     */
+    setTranscriptPath(path) {
+        this.transcriptPath = path;
+        this.toolResultsDir = resolveToolResultsDir(path);
+    }
+    /**
+     * Initialize tool-result-persistence state from already-loaded messages.
+     * Call this once per session, after setTranscriptPath, when resuming so
+     * the manager re-enters the same "frozen decision" state it had on the
+     * previous run. Without this, a resumed session would re-evaluate
+     * every result against the current threshold and might flip choices.
+     */
+    initReplacementStateFromMessages(messages) {
+        this.replacementState = reconstructContentReplacementState(messages);
+    }
+    /**
+     * Apply progressive context management (sync path).
+     * For Tier 2 (LLM summary), call manageAsync instead.
+     */
+    manage(messages) {
+        let result = messages;
+        // Tier 0a: Persist large tool_results to disk + replace with preview.
+        // Runs before any in-context truncation so the model gets a real
+        // filepath it can Read back, not a silent head/tail truncation.
+        result = this.persistLargeToolResults(result);
+        // Tier 0b: Hard truncate any oversized tool_result that survived
+        // persistence (e.g. persistence disabled, FS write failed, or a
+        // block was already frozen "don't persist" on a prior pass).
+        result = this.truncateToolResults(result);
+        // Tier 0c: Aggregate tool result budget (per-message) — char-level
+        // backstop for messages still over the limit after persistence.
+        result = applyToolResultBudget(result);
+        // Tier 1: microcompact — fingerprint old whitelisted tool_results.
+        // Only runs above the floor ratio: under-pressure context keeps full
+        // detail so the model isn't forced to re-Read files it just looked at.
+        const preTier1Tokens = this.estimateTokensHybrid(result);
+        if (preTier1Tokens > this.config.maxTokens * this.config.microcompactFloorRatio) {
+            const keepRecentN = this.config.microcompactKeepRecent ?? defaultKeepRecent(this.config.maxTokens);
+            // Capture rounds/tools synchronously from microcompact's onClear, but
+            // defer the token re-estimate until AFTER `result` has been reassigned
+            // to the compacted array — onClear fires before microcompact returns,
+            // so reading `result` inside it would see the pre-compact reference.
+            let clearedInfo = null;
+            result = microcompact(result, {
+                keepRecentN,
+                onClear: (info) => {
+                    clearedInfo = info;
+                },
+            });
+            if (clearedInfo) {
+                const after = this.estimateTokensHybrid(result);
+                logger.info("context.microcompact", {
+                    before: preTier1Tokens,
+                    after,
+                    keepRecentN,
+                    clearedRounds: clearedInfo.clearedRounds,
+                    toolNames: clearedInfo.toolNames,
+                });
+                this.onCompact?.({ strategy: "micro", before: preTier1Tokens, after });
+            }
+        }
+        // Hybrid token estimation walks every message; we cache it across the
+        // tier checks below and only recompute after a compaction shrinks `result`.
+        let tokens = this.estimateTokensHybrid(result);
+        // Tiers run in increasing severity. Each tier short-circuits its own
+        // arm but the next tier still runs if we're still above the next gate
+        // — a single pass can escalate micro → summary-replay → snip → window
+        //  → emergency when the model just dumped a flood of tool_results.
+        //
+        // Severity gates (fractions of maxTokens):
+        //   compactAtRatio       — start non-micro compaction (try summary first,
+        //                          else snip; snip is the cheapest sync option)
+        //   compactAtRatio + 0.05 — snip wasn't enough, do a window compact
+        //   summarizeAtRatio      — emergency window (smallest keep-tail)
+        const snipGate = this.config.maxTokens * this.config.compactAtRatio;
+        const windowGate = this.config.maxTokens * (this.config.compactAtRatio + 0.05);
+        const emergencyGate = this.config.maxTokens * this.config.summarizeAtRatio;
+        // Tier 2: prefer replaying a cached summary; otherwise snip
+        if (tokens > snipGate) {
+            const before = tokens;
+            if (this.lastSummary) {
+                const keepN = Math.max(8, Math.floor(result.length * 0.3));
+                result = applySummaryCompaction(result, this.lastSummary, keepN, this.transcriptPath);
+                this.lastSummary = undefined;
+                tokens = this.estimateTokensHybrid(result);
+                this.onCompact?.({ strategy: "summary", before, after: tokens });
+            }
+            else {
+                result = snipCompact(result, 3, 8);
+                tokens = this.estimateTokensHybrid(result);
+                this.onCompact?.({ strategy: "snip", before, after: tokens });
+            }
+        }
+        // Tier 2b: snip didn't free enough — fall back to window compact
+        if (tokens > windowGate) {
+            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 });
+        }
+        // Tier 3: emergency window with a tiny tail — last resort before the
+        // request would otherwise blow the model's context.
+        if (tokens > emergencyGate) {
+            const before = tokens;
+            result = windowCompact(result, 6);
+            tokens = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "emergency", before, after: tokens });
+        }
+        return result;
+    }
+    /**
+     * Async context management — attempts LLM summarization before falling back.
+     * Call this when you have access to the LLM (between turns).
+     */
+    async manageAsync(messages) {
+        let result = messages;
+        // Tier 0a: Persist large tool_results to disk + replace with preview.
+        result = this.persistLargeToolResults(result);
+        // Tier 0b: Hard truncate oversized tool_result blocks that weren't
+        // persisted (persistence disabled, FS error, or already frozen).
+        result = this.truncateToolResults(result);
+        // Tier 0c: Aggregate tool result budget (per-message)
+        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 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.
+            let clearedInfo = null;
+            result = microcompact(result, {
+                keepRecentN,
+                onClear: (info) => {
+                    clearedInfo = info;
+                },
+            });
+            if (clearedInfo) {
+                const after = this.estimateTokensHybrid(result);
+                logger.info("context.microcompact", {
+                    before: preTier1Tokens,
+                    after,
+                    keepRecentN,
+                    clearedRounds: clearedInfo.clearedRounds,
+                    toolNames: clearedInfo.toolNames,
+                });
+                this.onCompact?.({ strategy: "micro", before: preTier1Tokens, after });
+            }
+        }
+        const 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;
+                    }
+                }
+            }
+            catch (err) {
+                this.consecutiveSummaryFailures++;
+                logger.warn("context.summary_failed", {
+                    failures: this.consecutiveSummaryFailures,
+                    error: err.message,
+                });
+            }
+        }
+        // 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().
+        let live = tokens;
+        const snipGate = this.config.maxTokens * this.config.compactAtRatio;
+        const windowGate = this.config.maxTokens * (this.config.compactAtRatio + 0.05);
+        const emergencyGate = this.config.maxTokens * this.config.summarizeAtRatio;
+        // Tier 2 fallback: snip first (cheapest sync option)
+        if (live > snipGate) {
+            const before = live;
+            result = snipCompact(result, 3, 8);
+            live = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "snip", before, after: live });
+        }
+        // Tier 2b: window compact when snip didn't free enough
+        if (live > windowGate) {
+            const before = live;
+            const keepN = Math.max(10, Math.floor(result.length * 0.4));
+            result = windowCompact(result, keepN);
+            live = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "window", before, after: live });
+        }
+        // Tier 3: Emergency
+        if (live > emergencyGate) {
+            const before = live;
+            result = windowCompact(result, 6);
+            live = this.estimateTokensHybrid(result);
+            this.onCompact?.({ strategy: "emergency", before, after: live });
+        }
+        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
+     * (e.g. unit tests that exercise compaction directly without a session).
+     */
+    persistLargeToolResults(messages) {
+        if (!this.toolResultsDir)
+            return messages;
+        if (!this.replacementState) {
+            this.replacementState = createContentReplacementState();
+        }
+        return applyToolResultPersistence(messages, {
+            toolResultsDir: this.toolResultsDir,
+            state: this.replacementState,
+            onPersist: (info) => {
+                logger.info("context.tool_result_persisted", info);
+            },
+        });
+    }
+    /**
+     * Truncate oversized tool results in messages.
+     */
+    truncateToolResults(messages) {
+        const maxChars = this.config.maxToolResultChars;
+        let modified = false;
+        const result = messages.map((msg) => {
+            if (!Array.isArray(msg.content))
+                return msg;
+            const newContent = msg.content.map((block) => {
+                if (block.type === "tool_result" && typeof block.content === "string") {
+                    if (block.content.length > maxChars) {
+                        modified = true;
+                        return { ...block, content: truncateToolResult(block.content, maxChars) };
+                    }
+                }
+                return block;
+            });
+            return modified ? { ...msg, content: newContent } : msg;
+        });
+        return result;
+    }
+    /**
+     * Reactive compaction check — call during streaming to detect if
+     * token usage is approaching the limit mid-turn.
+     * Returns true if emergency compaction should be triggered.
+     */
+    shouldReactiveCompact(messages, currentResponseTokens) {
+        const msgTokens = this.estimateTokensHybrid(messages);
+        const total = msgTokens + currentResponseTokens;
+        // Trigger at the same gate as the emergency tier — keeps the streaming
+        // reactive check aligned with the post-turn ladder.
+        return total > this.config.maxTokens * this.config.summarizeAtRatio;
+    }
+    /**
+     * Check if context is approaching limits.
+     */
+    checkLimits(messages) {
+        const tokens = this.estimateTokensHybrid(messages);
+        const ratio = tokens / this.config.maxTokens;
+        return {
+            tokens,
+            ratio,
+            needsCompact: ratio >= this.config.compactAtRatio,
+            needsEmergency: ratio >= this.config.summarizeAtRatio,
+        };
+    }
+    /**
+     * Deduplicate tool calls by hashing arguments.
+     */
+    deduplicateToolCalls(calls) {
+        const toExecute = [];
+        const cached = [];
+        for (const call of calls) {
+            const hash = this.hashCall(call.toolName, call.args);
+            const existing = this.toolCallHashes.get(hash);
+            if (existing && existing.count >= 2) {
+                cached.push({ ...call, result: existing.lastResult });
+                existing.count++;
+            }
+            else {
+                toExecute.push(call);
+            }
+        }
+        return { toExecute, cached };
+    }
+    /**
+     * Record a tool call result for dedup tracking.
+     */
+    recordToolResult(toolName, args, result) {
+        const hash = this.hashCall(toolName, args);
+        const existing = this.toolCallHashes.get(hash);
+        if (existing) {
+            existing.count++;
+            existing.lastResult = result;
+        }
+        else {
+            this.toolCallHashes.set(hash, { count: 1, lastResult: result });
+        }
+    }
+    hashCall(toolName, args) {
+        return `${toolName}:${JSON.stringify(args)}`;
+    }
+}

package/dist/context/token-counter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Token counter — more accurate token estimation.
+ *
+ * Uses a character-based heuristic tuned per language/content type,
+ * with cache-aware accounting for prompt caching.
+ */
+import type { Message } from "../types.js";
+/**
+ * Estimate token count for a string, detecting content type.
+ */
+export declare function estimateStringTokens(text: string): number;
+/**
+ * Estimate token count for a message array.
+ */
+export declare function estimateMessagesTokens(messages: Message[]): number;
+/**
+ * Context window usage report.
+ */
+export interface ContextUsage {
+    usedTokens: number;
+    maxTokens: number;
+    usagePercent: number;
+    systemPromptTokens: number;
+    messagesTokens: number;
+    headroom: number;
+}
+export declare function calculateContextUsage(messages: Message[], systemPrompt: string, maxTokens: number): ContextUsage;

package/dist/context/token-counter.js

@@ -0,0 +1,91 @@
+/**
+ * Token counter — more accurate token estimation.
+ *
+ * Uses a character-based heuristic tuned per language/content type,
+ * with cache-aware accounting for prompt caching.
+ */
+/**
+ * Token-to-character ratios by content type.
+ * These are empirical averages from Claude/GPT tokenizers.
+ */
+const RATIOS = {
+    english: 4.0, // ~4 chars per token for English prose
+    code: 3.2, // ~3.2 chars per token for code (more tokens per char)
+    json: 3.5, // JSON structures
+    mixed: 3.6, // Mixed content (typical for tool results)
+    cjk: 1.5, // CJK characters: ~1.5 chars per token
+};
+/**
+ * Estimate token count for a string, detecting content type.
+ */
+export function estimateStringTokens(text) {
+    if (!text)
+        return 0;
+    // Detect CJK content ratio
+    const cjkChars = (text.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) ?? []).length;
+    const cjkRatio = cjkChars / text.length;
+    if (cjkRatio > 0.3) {
+        // Weighted average for mixed CJK/ASCII
+        const cjkTokens = cjkChars / RATIOS.cjk;
+        const otherChars = text.length - cjkChars;
+        const otherTokens = otherChars / RATIOS.english;
+        return Math.ceil(cjkTokens + otherTokens);
+    }
+    // Detect code
+    const codeIndicators = ["{", "}", "(", ")", ";", "=>", "import ", "function ", "class ", "const "];
+    const codeScore = codeIndicators.reduce((s, ind) => s + (text.includes(ind) ? 1 : 0), 0);
+    if (codeScore >= 3)
+        return Math.ceil(text.length / RATIOS.code);
+    if (text.startsWith("{") || text.startsWith("["))
+        return Math.ceil(text.length / RATIOS.json);
+    return Math.ceil(text.length / RATIOS.english);
+}
+/**
+ * Estimate token count for a message array.
+ */
+export function estimateMessagesTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        // Per-message overhead (role, formatting) ≈ 4 tokens
+        total += 4;
+        if (typeof msg.content === "string") {
+            total += estimateStringTokens(msg.content);
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const block of msg.content) {
+                total += estimateBlockTokens(block);
+            }
+        }
+    }
+    return total;
+}
+/**
+ * Estimate tokens for a content block.
+ */
+function estimateBlockTokens(block) {
+    let tokens = 2; // Block overhead
+    if (block.text)
+        tokens += estimateStringTokens(block.text);
+    if (block.content && typeof block.content === "string") {
+        tokens += estimateStringTokens(block.content);
+    }
+    if (block.input) {
+        tokens += estimateStringTokens(JSON.stringify(block.input));
+    }
+    if (block.name)
+        tokens += estimateStringTokens(block.name);
+    return tokens;
+}
+export function calculateContextUsage(messages, systemPrompt, maxTokens) {
+    const systemPromptTokens = estimateStringTokens(systemPrompt);
+    const messagesTokens = estimateMessagesTokens(messages);
+    const usedTokens = systemPromptTokens + messagesTokens;
+    return {
+        usedTokens,
+        maxTokens,
+        usagePercent: (usedTokens / maxTokens) * 100,
+        systemPromptTokens,
+        messagesTokens,
+        headroom: maxTokens - usedTokens,
+    };
+}