@miphamai/cli 0.4.0 → 0.5.0

package/src/artifacts/versioning.ts

@@ -0,0 +1,127 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DEFAULT_VERSIONS_DIR = join(homedir(), '.mipham', 'artifacts')
+
+export interface ArtifactVersion {
+  name: string
+  version: number
+  path: string
+  createdAt: string
+  size: number
+}
+
+/**
+ * Manages artifact version snapshots on disk.
+ *
+ * Directory layout:
+ *   <dir>/<name>/versions/v1.html
+ *   <dir>/<name>/versions/v2.html
+ *   <dir>/<name>/current.html     (latest snapshot)
+ *   <dir>/<name>/manifest.json    ({ name, currentVersion, versionCount })
+ */
+export class ArtifactVersioning {
+  private dir: string
+
+  constructor(dir?: string) {
+    this.dir = dir ?? DEFAULT_VERSIONS_DIR
+    mkdirSync(this.dir, { recursive: true })
+  }
+
+  /** Save a new version of an artifact. Returns the assigned version number. */
+  saveVersion(name: string, content: string): number {
+    const artifactDir = join(this.dir, name)
+    const versionsDir = join(artifactDir, 'versions')
+    mkdirSync(versionsDir, { recursive: true })
+
+    // Determine next version number
+    const existing = this.listVersions(name)
+    const nextVersion = (existing.length > 0 ? Math.max(...existing.map((v) => v.version)) : 0) + 1
+
+    // Save versioned file
+    const versionPath = join(versionsDir, `v${nextVersion}.html`)
+    writeFileSync(versionPath, content, 'utf-8')
+
+    // Update current.html
+    writeFileSync(join(artifactDir, 'current.html'), content, 'utf-8')
+
+    // Update manifest
+    writeFileSync(
+      join(artifactDir, 'manifest.json'),
+      JSON.stringify(
+        {
+          name,
+          currentVersion: nextVersion,
+          versionCount: nextVersion,
+        },
+        null,
+        2,
+      ),
+    )
+
+    return nextVersion
+  }
+
+  /** List all saved versions for an artifact, newest first. */
+  listVersions(name: string): ArtifactVersion[] {
+    const versionsDir = join(this.dir, name, 'versions')
+    if (!existsSync(versionsDir)) return []
+
+    try {
+      return readdirSync(versionsDir)
+        .filter((f) => f.startsWith('v') && f.endsWith('.html'))
+        .map((f) => {
+          const vNum = parseInt(f.replace('v', '').replace('.html', ''), 10)
+          const path = join(versionsDir, f)
+          const stat = statSync(path)
+          return {
+            name,
+            version: vNum,
+            path,
+            createdAt: stat.birthtime.toISOString(),
+            size: stat.size,
+          }
+        })
+        .sort((a, b) => b.version - a.version)
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Get artifact content.
+   * - If a version number is given, returns that specific version.
+   * - Otherwise returns the latest (current.html).
+   * Returns null if the requested version does not exist.
+   */
+  getVersion(name: string, version?: number): string | null {
+    const artifactDir = join(this.dir, name)
+
+    if (version !== undefined) {
+      const vPath = join(artifactDir, 'versions', `v${version}.html`)
+      return existsSync(vPath) ? readFileSync(vPath, 'utf-8') : null
+    }
+
+    const currentPath = join(artifactDir, 'current.html')
+    return existsSync(currentPath) ? readFileSync(currentPath, 'utf-8') : null
+  }
+
+  /** Produce a simple line-by-line text diff between two versions. */
+  diff(name: string, v1: number, v2: number): string {
+    const content1 = this.getVersion(name, v1) || ''
+    const content2 = this.getVersion(name, v2) || ''
+    const lines1 = content1.split('\n')
+    const lines2 = content2.split('\n')
+
+    const diffLines: string[] = []
+    const maxLen = Math.max(lines1.length, lines2.length)
+    for (let i = 0; i < maxLen; i++) {
+      if (lines1[i] !== lines2[i]) {
+        if (lines1[i] !== undefined) diffLines.push(`- ${lines1[i]}`)
+        if (lines2[i] !== undefined) diffLines.push(`+ ${lines2[i]}`)
+      }
+    }
+    return diffLines.length > 0 ? diffLines.join('\n') : '(no changes)'
+  }
+}

package/src/core/context-compact.ts

@@ -0,0 +1,50 @@
+import type { ContextManager, Summarizer } from './context'
+import { snipMessages } from './context-snip'
+
+/**
+ * Layer 3: Reactive Compact — API-based summarization.
+ *
+ * When the context exceeds the compaction threshold, uses an LLM summarizer
+ * to condense the conversation history, keeping recent messages intact.
+ *
+ * After compaction, the context contains:
+ * 1. A summary message of the truncated history
+ * 2. The most recent N messages (kept intact)
+ * 3. The system prompt (unchanged)
+ */
+export async function reactiveCompact(
+  context: ContextManager,
+  summarizer: Summarizer,
+  heading: string,
+  keepRecent: number = 20,
+): Promise<void> {
+  const messages = context.getMessages()
+
+  if (messages.length <= keepRecent + 4) return
+
+  // First, run snip to remove empty pairs
+  const { messages: snipped } = snipMessages(messages)
+
+  if (snipped.length <= keepRecent + 4) return
+
+  // Split: old messages to summarize, recent messages to keep
+  const toSummarize = snipped.slice(0, -keepRecent)
+  const toKeep = snipped.slice(-keepRecent)
+
+  // Generate summary
+  let summary: string
+  try {
+    summary = await summarizer(toSummarize, heading)
+  } catch {
+    // On summarizer failure, do a simple truncation
+    summary = `Earlier conversation (${toSummarize.length} messages) omitted due to context limits.`
+  }
+
+  // Rebuild messages: summary + recent
+  const summaryMsg = {
+    role: 'user' as const,
+    content: `[Earlier conversation summary — ${heading}]: ${summary.slice(0, 2000)}`,
+  }
+
+  context.replaceMessages([summaryMsg, ...toKeep])
+}

package/src/core/context-drain.ts

@@ -0,0 +1,54 @@
+import type { ContextManager } from './context'
+
+const MINIMAL_KEEP = 5
+let drainLevel = 0
+
+/**
+ * Layer 4: Emergency Drain — 413 error recovery.
+ *
+ * Called when a 413 (context too large) error is received.
+ * Progressively strips messages until the context fits:
+ *
+ * Level 1: Drop earliest 50% of messages
+ * Level 2+: Keep only system prompt + last 5 messages
+ *
+ * Returns true if recovery was possible, false if context is already minimal.
+ */
+export async function emergencyDrain(context: ContextManager): Promise<boolean> {
+  const messages = context.getMessages()
+
+  if (messages.length <= MINIMAL_KEEP) {
+    return false // Already minimal, cannot drain further
+  }
+
+  if (drainLevel === 0) {
+    // First attempt: drop earliest 50%
+    const keepCount = Math.max(MINIMAL_KEEP, Math.floor(messages.length / 2))
+    const kept = messages.slice(-keepCount)
+    context.replaceMessages(kept)
+    drainLevel++
+    return true
+  }
+
+  // Subsequent attempts: keep only system + last MINIMAL_KEEP messages
+  const kept = messages.slice(-MINIMAL_KEEP)
+
+  // Add a summary placeholder if we're dropping a lot
+  if (messages.length > MINIMAL_KEEP * 2) {
+    const summaryMsg = {
+      role: 'user' as const,
+      content: `[Emergency context drain: ${messages.length - MINIMAL_KEEP} earlier messages discarded due to token limit.]`,
+    }
+    context.replaceMessages([summaryMsg, ...kept])
+  } else {
+    context.replaceMessages(kept)
+  }
+
+  drainLevel++
+  return true
+}
+
+/** Reset drain level (call at session start). */
+export function resetDrainLevel(): void {
+  drainLevel = 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))
+}