@miphamai/cli 0.3.0 → 0.5.0

package/src/core/context-microcompact.ts

@@ -0,0 +1,132 @@
+import type { Message, ToolResultContent } from '@mipham/shared'
+import type { CacheTracker } from './context-token'
+import { estimateMessageTokens } from './context-token'
+
+const PLACEHOLDER = '[earlier result omitted]'
+
+interface MicrocompactOptions {
+  keepRecent: number // number of recent tool-call pairs to keep intact
+}
+
+interface MicrocompactResult {
+  messages: Message[]
+  tokensSaved: number
+}
+
+/**
+ * Layer 2: Cache-aware micro-compression.
+ *
+ * Replaces old tool_result content with a placeholder, preserving message
+ * structure. Only compresses messages NOT in the prompt cache to avoid
+ * cache invalidation costs.
+ */
+export function microcompact(
+  messages: Message[],
+  cacheTracker: CacheTracker,
+  options: MicrocompactOptions = { keepRecent: 3 },
+): MicrocompactResult {
+  const result: Message[] = []
+  let tokensSaved = 0
+
+  // Identify tool-call pairs (user query -> assistant tool_use -> user tool_result)
+  // Count from the end to keep the most recent ones intact
+  const pairCount = countToolPairs(messages)
+  const compressBeforePair = Math.max(0, pairCount - options.keepRecent)
+
+  let pairIndex = 0
+  let i = 0
+
+  while (i < messages.length) {
+    const msg = messages[i]!
+
+    // Check if this starts a tool-call pair
+    if (isToolResultUserMessage(msg) && pairIndex < compressBeforePair) {
+      // Don't compress if it's in the prompt cache
+      if (!cacheTracker.isInCache(msg)) {
+        const compressed = compressToolResult(msg)
+        result.push(compressed)
+        tokensSaved += estimateMessageTokens(msg) - estimateMessageTokens(compressed)
+        i++
+        pairIndex++
+        continue
+      }
+    }
+
+    // Count pairs as we go
+    if (isToolResultUserMessage(msg)) {
+      pairIndex++
+    }
+
+    result.push(msg)
+    i++
+  }
+
+  return { messages: result, tokensSaved }
+}
+
+function countToolPairs(messages: Message[]): number {
+  let count = 0
+  for (const msg of messages) {
+    if (isToolResultUserMessage(msg)) count++
+  }
+  return count
+}
+
+function isToolResultUserMessage(msg: Message): boolean {
+  if (msg.role !== 'user') return false
+  if (!Array.isArray(msg.content)) return false
+  return msg.content.some(
+    (block: unknown) =>
+      block !== null &&
+      typeof block === 'object' &&
+      (block as unknown as Record<string, unknown>).type === 'tool_result',
+  )
+}
+
+function compressToolResult(msg: Message): Message {
+  if (!Array.isArray(msg.content)) return msg
+
+  const compressed = msg.content.map((block: unknown) => {
+    if (
+      block !== null &&
+      typeof block === 'object' &&
+      (block as unknown as Record<string, unknown>).type === 'tool_result'
+    ) {
+      return {
+        ...(block as object),
+        content: PLACEHOLDER,
+      } as ToolResultContent
+    }
+    return block as ToolResultContent
+  })
+
+  return { ...msg, content: compressed }
+}
+
+/**
+ * Decide whether microcompaction is worth it.
+ *
+ * Only compress when tokens saved > tokens lost from cache invalidation.
+ * The multiplier of 1.5 provides a safety margin.
+ */
+export function shouldMicrocompact(
+  messages: Message[],
+  cacheTracker: CacheTracker,
+  _threshold: number,
+): boolean {
+  let savingsTokens = 0
+  let cacheLossTokens = 0
+
+  for (const msg of messages) {
+    if (isToolResultUserMessage(msg)) {
+      const tokens = estimateMessageTokens(msg)
+      if (cacheTracker.isInCache(msg)) {
+        cacheLossTokens += tokens
+      } else {
+        savingsTokens += tokens * 0.5 // we save ~50% by replacing content
+      }
+    }
+  }
+
+  return savingsTokens > cacheLossTokens * 1.5
+}

package/src/core/context-snip.ts

@@ -0,0 +1,74 @@
+import type { Message } from '../shared/index.js'
+
+interface SnipResult {
+  messages: Message[]
+  removed: number
+}
+
+/**
+ * Layer 1: Zero-cost pruning.
+ *
+ * Removes tool_use + empty tool_result message pairs that carry no
+ * information value. This is a pure data transformation — no API calls.
+ *
+ * A pair is eligible for removal when:
+ * - The assistant message contains only a tool_use block
+ * - The immediately following user message contains only a tool_result
+ *   with empty or whitespace-only content
+ */
+export function snipMessages(messages: Message[]): SnipResult {
+  if (messages.length < 2) return { messages: [...messages], removed: 0 }
+
+  const result: Message[] = []
+  let removed = 0
+  let i = 0
+
+  while (i < messages.length) {
+    // Look for a tool_use assistant message followed by empty tool_result
+    if (
+      i + 1 < messages.length &&
+      messages[i]!.role === 'assistant' &&
+      isOnlyToolUse(messages[i]!) &&
+      messages[i + 1]!.role === 'user' &&
+      isEmptyToolResult(messages[i + 1]!)
+    ) {
+      removed += 2
+      i += 2
+      continue
+    }
+
+    result.push(messages[i]!)
+    i++
+  }
+
+  return { messages: result, removed }
+}
+
+function isOnlyToolUse(msg: Message): boolean {
+  if (!Array.isArray(msg.content)) return false
+  const nonToolUse = msg.content.filter(
+    (block: unknown) =>
+      !(
+        block &&
+        typeof block === 'object' &&
+        (block as Record<string, unknown>).type === 'tool_use'
+      ),
+  )
+  // Must have at least one tool_use and nothing else substantial
+  const hasToolUse = msg.content.some(
+    (block: unknown) =>
+      block && typeof block === 'object' && (block as Record<string, unknown>).type === 'tool_use',
+  )
+  return hasToolUse && nonToolUse.length === 0
+}
+
+function isEmptyToolResult(msg: Message): boolean {
+  if (!Array.isArray(msg.content)) return false
+  return msg.content.every((block: unknown) => {
+    if (!block || typeof block !== 'object') return false
+    const b = block as Record<string, unknown>
+    if (b.type !== 'tool_result') return true // non-tool_result blocks don't count
+    const content = String(b.content || '')
+    return content.trim().length === 0
+  })
+}

package/src/core/context-token.ts

@@ -0,0 +1,108 @@
+import type { Message } from '@mipham/shared'
+
+export interface CacheStatus {
+  totalMessages: number
+  cachedMessages: number
+  cachedTokens: number
+  uncachedTokens: number
+}
+
+export interface CacheTracker {
+  /** Returns true if the message is currently held in the provider's prompt cache. */
+  isInCache(msg: Message): boolean
+  /** Returns a snapshot of the cache state for metrics / logging. */
+  getStatus(): CacheStatus
+  /** Clear the tracker state (does NOT evict from provider cache). */
+  invalidate(): void
+}
+
+/**
+ * A no-op cache tracker for use when prompt caching is unavailable or disabled.
+ * Every message reports as uncached, so microcompaction always considers savings.
+ */
+export class NoopCacheTracker implements CacheTracker {
+  private messageCount = 0
+
+  isInCache(_msg: Message): boolean {
+    return false
+  }
+
+  getStatus(): CacheStatus {
+    return {
+      totalMessages: this.messageCount,
+      cachedMessages: 0,
+      cachedTokens: 0,
+      uncachedTokens: 0,
+    }
+  }
+
+  /** Register a batch of messages for status tracking. */
+  track(messages: Message[]): void {
+    this.messageCount = messages.length
+  }
+
+  invalidate(): void {
+    this.messageCount = 0
+  }
+}
+
+/**
+ * Estimate the token count for a single message.
+ *
+ * Uses the same character-class-aware heuristic as ContextManager.estimateTokens():
+ *   - CJK / emoji: ~1.5 chars per token
+ *   - Other scripts: ~4 chars per token
+ */
+export function estimateMessageTokens(msg: Message): number {
+  const text = extractMessageText(msg)
+  return estimateStringTokens(text)
+}
+
+function extractMessageText(msg: Message): string {
+  if (typeof msg.content === 'string') {
+    return msg.content
+  }
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .map((block) => {
+        if (block && typeof block === 'object') {
+          const b = block as unknown as Record<string, unknown>
+          if (b.type === 'text') return String(b.text ?? '')
+          if (b.type === 'tool_use') return JSON.stringify(b.input ?? {})
+          if (b.type === 'tool_result') return String(b.content ?? '')
+          if (b.type === 'image_url') return '[image]'
+        }
+        return ''
+      })
+      .join(' ')
+  }
+  return ''
+}
+
+function estimateStringTokens(text: string): number {
+  if (!text) return 0
+
+  let cjk = 0
+  let latin = 0
+
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)!
+    // CJK Unified Ideographs, Hangul, Kana, CJK Extensions, fullwidth forms
+    if (
+      (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+      (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext-A
+      (cp >= 0x20000 && cp <= 0x2a6df) || // CJK Ext-B
+      (cp >= 0xac00 && cp <= 0xd7af) || // Hangul
+      (cp >= 0x3040 && cp <= 0x30ff) || // Hiragana + Katakana
+      (cp >= 0xff01 && cp <= 0xff60) || // Fullwidth
+      (cp >= 0x1f300 && cp <= 0x1f9ff) // Emoji / pictographs
+    ) {
+      cjk++
+    } else {
+      latin++
+    }
+  }
+
+  // CJK: ~1.5 chars/token, Latin/other: ~4 chars/token
+  return Math.max(1, Math.ceil(cjk / 1.5 + latin / 4))
+}

package/src/core/context.ts

@@ -1,4 +1,9 @@
 import type { Message } from '../shared/index.ts'
+import { snipMessages } from './context-snip'
+import { microcompact } from './context-microcompact'
+import { reactiveCompact } from './context-compact'
+import { emergencyDrain } from './context-drain'
+import { NoopCacheTracker, type CacheTracker, type CacheStatus } from './context-token'
 
 export type Summarizer = (messages: Message[], heading: string) => Promise<string>
 
@@ -7,6 +12,17 @@ interface ContextConfig {
   compactionThreshold: number // e.g. 0.9 → compact at 90% usage
 }
 
+export interface CompactionStats {
+  snipCount: number
+  snipMessagesRemoved: number
+  microcompactCount: number
+  microcompactTokensSaved: number
+  compactCount: number
+  compactTokensSaved: number
+  drainCount: number
+  lastCompaction: Date | null
+}
+
 interface Checkpoint {
   id: number
   messages: Message[]
@@ -23,6 +39,20 @@ export class ContextManager {
   private checkpointCounter = 0
   private summarizer?: Summarizer
 
+  // ── Compression state ──
+  private cacheTracker: CacheTracker = new NoopCacheTracker()
+  private compactionStats: CompactionStats = {
+    snipCount: 0,
+    snipMessagesRemoved: 0,
+    microcompactCount: 0,
+    microcompactTokensSaved: 0,
+    compactCount: 0,
+    compactTokensSaved: 0,
+    drainCount: 0,
+    lastCompaction: null,
+  }
+  private compressionPending = false
+
   constructor(private config: ContextConfig) {}
 
   /** Set an optional LLM summarizer for intelligent compaction. */
@@ -44,6 +74,9 @@ export class ContextManager {
     this.estimatedTokens += this.estimateTokens(
       typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
     )
+
+    // Auto-trigger compression checks (fire-and-forget, don't await)
+    this.checkCompression()
   }
 
   getMessages(): Message[] {
@@ -102,6 +135,21 @@ export class ContextManager {
     return this.messages.length
   }
 
+  /**
+   * Replace all messages atomically (used by compaction layers).
+   * Preserves system prompt. Does NOT trigger compaction checks.
+   */
+  replaceMessages(messages: Message[]): void {
+    this.messages = messages
+    // Re-estimate tokens
+    this.estimatedTokens = this.estimateTokens(this.systemPrompt)
+    for (const msg of messages) {
+      this.estimatedTokens += this.estimateTokens(
+        typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+      )
+    }
+  }
+
   // ── Checkpoint / Rewind ──
 
   saveCheckpoint(label = 'auto'): number {
@@ -153,6 +201,127 @@ export class ContextManager {
     return this.checkpoints.at(-1)?.id
   }
 
+  // ── Cache tracker integration ──
+
+  /** Register a cache tracker for cache-aware microcompaction decisions. */
+  setCacheTracker(tracker: CacheTracker): void {
+    this.cacheTracker = tracker
+  }
+
+  /** Get a snapshot of the provider prompt-cache state. */
+  getCacheStatus(): CacheStatus {
+    return this.cacheTracker.getStatus()
+  }
+
+  // ── Compression stats ──
+
+  /** Return a copy of the current compaction statistics. */
+  getCompactionStats(): CompactionStats {
+    return { ...this.compactionStats }
+  }
+
+  // ── 413 recovery ──
+
+  /**
+   * Emergency context drain for 413 (context too large) errors.
+   * Progressively strips messages until the context fits.
+   * Returns true if recovery was possible, false if already minimal.
+   */
+  async on413Error(): Promise<boolean> {
+    const result = await emergencyDrain(this)
+    if (result) {
+      this.compactionStats.drainCount++
+      this.compactionStats.lastCompaction = new Date()
+    }
+    return result
+  }
+
+  // ── Forced compaction (e.g. /compact command) ──
+
+  /**
+   * Force compaction of the conversation history.
+   *
+   * Uses the provided summarizer, the internal summarizer, or falls back
+   * to emergency drain if neither is available.
+   */
+  async forceCompact(heading: string, summarizer?: Summarizer): Promise<void> {
+    const beforeTokens = this.estimatedTokens
+
+    if (summarizer) {
+      await reactiveCompact(this, summarizer, heading)
+    } else if (this.summarizer) {
+      await reactiveCompact(this, this.summarizer, heading)
+    } else {
+      // Fallback: simple truncation via drain
+      await emergencyDrain(this)
+    }
+
+    const tokensSaved = beforeTokens - this.estimatedTokens
+    this.compactionStats.compactCount++
+    if (tokensSaved > 0) {
+      this.compactionStats.compactTokensSaved += tokensSaved
+    }
+    this.compactionStats.lastCompaction = new Date()
+  }
+
+  // ── Private compression helpers ──
+
+  /**
+   * Check estimated token usage and auto-trigger compression.
+   *
+   * - At 70%: run microcompact (fire-and-forget)
+   * - At 85%: the existing needsCompaction() serves as a compact hint
+   */
+  private checkCompression(): void {
+    if (this.compressionPending) return
+
+    const usage = this.estimatedTokens / this.config.maxTokens
+
+    if (usage > 0.7) {
+      this.compressionPending = true
+      // Schedule microcompact asynchronously (fire-and-forget)
+      Promise.resolve().then(() => {
+        this.runMicrocompact()
+        this.compressionPending = false
+      })
+    }
+  }
+
+  /** Run snip + microcompact inline and update stats. */
+  private runMicrocompact(): void {
+    const { messages: snipped, removed } = snipMessages(this.messages)
+
+    if (removed > 0) {
+      this.compactionStats.snipCount++
+      this.compactionStats.snipMessagesRemoved += removed
+    }
+
+    // Microcompact: compress tool_results not needed for recent context
+    const keepRecent = 3
+    const { messages: compacted, tokensSaved } = microcompact(snipped, this.cacheTracker, {
+      keepRecent,
+    })
+
+    if (tokensSaved > 0) {
+      this.compactionStats.microcompactCount++
+      this.compactionStats.microcompactTokensSaved += tokensSaved
+      this.compactionStats.lastCompaction = new Date()
+    }
+
+    this.messages = compacted
+    this.reEstimateTokens()
+  }
+
+  /** Re-estimate tokens from system prompt + current messages. */
+  private reEstimateTokens(): void {
+    this.estimatedTokens = this.estimateTokens(this.systemPrompt)
+    for (const msg of this.messages) {
+      this.estimatedTokens += this.estimateTokens(
+        typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+      )
+    }
+  }
+
   /**
    * Estimate token count for a text string.
    *