@miphamai/cli 0.33.0 → 0.33.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/cross-session/file-inbox.ts

@@ -23,12 +23,23 @@ const INBOX_DIR = join(MIPHAM_HOME, 'inbox')
  * Each message file is named: <ISO-timestamp>-<msg-id>.json
  */
 export class FileInboxTransport implements CrossSessionTransport {
+  private initialized = false
+
   private ensureDir(dir: string): void {
     mkdirSync(dir, { recursive: true })
   }
 
+  /** Ensure the inbox root directory exists (call on first use). */
+  private ensureInboxRoot(): void {
+    if (!this.initialized) {
+      this.ensureDir(INBOX_DIR)
+      this.initialized = true
+    }
+  }
+
   async send(from: SessionInfo, toSessionId: string, msg: AgentMessage): Promise<boolean> {
     try {
+      this.ensureInboxRoot()
       const inboxDir = join(INBOX_DIR, toSessionId)
       this.ensureDir(inboxDir)
 
@@ -36,13 +47,17 @@ export class FileInboxTransport implements CrossSessionTransport {
       const filename = `${timestamp}-${msg.id}.json`
       const filePath = join(inboxDir, filename)
 
+      // Serialize with structured sender fields
+      const envelope = {
+        ...msg,
+        senderName: from.id,
+        senderMachine: from.machine,
+        senderSession: from.id,
+      }
+
       // Atomic write: temp file then rename
       const tmpPath = filePath + '.tmp'
-      writeFileSync(
-        tmpPath,
-        JSON.stringify({ ...msg, _fromSession: from.id, _fromMachine: from.machine }, null, 2),
-        'utf-8',
-      )
+      writeFileSync(tmpPath, JSON.stringify(envelope, null, 2), 'utf-8')
       renameSync(tmpPath, filePath)
 
       return true
@@ -52,6 +67,8 @@ export class FileInboxTransport implements CrossSessionTransport {
   }
 
   async poll(sessionId: string): Promise<AgentMessage[]> {
+    // Fix 6: Ensure inbox root exists before checking subdirectory
+    this.ensureInboxRoot()
     const inboxDir = join(INBOX_DIR, sessionId)
     if (!existsSync(inboxDir)) return []
 
@@ -65,21 +82,22 @@ export class FileInboxTransport implements CrossSessionTransport {
         try {
           const raw = readFileSync(join(inboxDir, file), 'utf-8')
           const parsed = JSON.parse(raw) as AgentMessage & {
-            _fromSession?: string
-            _fromMachine?: string
+            senderName?: string
+            senderMachine?: string
+            senderSession?: string
           }
 
-          // Build the message body with cross-session origin prefix
-          const originPrefix = parsed._fromSession
-            ? `[From: ${parsed._fromSession}@${parsed._fromMachine || 'unknown'}]\n\n`
-            : ''
+          // Fix 5: Structured sender display — separate From: line before body
+          const senderName = parsed.senderName || parsed.from || 'unknown'
+          const senderMachine = parsed.senderMachine || ''
+          const originLine = `[From: ${senderName}${senderMachine ? ` @ ${senderMachine}` : ''}]`
 
           messages.push({
             id: parsed.id,
             from: parsed.from,
             to: parsed.to,
             summary: parsed.summary,
-            message: `${originPrefix}${parsed.message}`,
+            message: `${originLine}\n${parsed.message}`,
             timestamp: new Date(parsed.timestamp),
             read: parsed.read,
             type: parsed.type,

package/src/core/compaction-progress.ts

@@ -0,0 +1,205 @@
+/**
+ * P1.1: Compaction Progress Tracker
+ *
+ * Provides user-visible progress feedback during context compaction:
+ *   - Phase indicator (which compaction layer is active)
+ *   - Message count (how many messages being processed)
+ *   - Retry countdown for API-based summarization
+ *   - Stuck detection hints
+ *
+ * Designed as an event emitter that the UI layer subscribes to.
+ * Falls back to stderr output when no UI subscriber is registered.
+ */
+
+// ── Types ──
+
+export type CompactionPhase =
+  'microcompact' | 'snip' | 'reactive-compact' | 'emergency-drain' | 'complete'
+
+export interface CompactionStatus {
+  phase: CompactionPhase
+  /** Human-readable description of current action */
+  message: string
+  /** 0-100 percentage, or -1 if indeterminate */
+  percent: number
+  /** Total messages before compaction */
+  messagesBefore: number
+  /** Messages remaining after compaction */
+  messagesAfter: number
+  /** Tokens before compaction */
+  tokensBefore: number
+  /** Tokens after compaction */
+  tokensAfter: number
+  /** Elapsed ms since compaction started */
+  elapsedMs: number
+  /** Retry count for summarization API calls */
+  retryCount: number
+  /** Whether a retry is in progress */
+  retrying: boolean
+  /** Whether the compaction appears stuck (no progress for >30s) */
+  stuck: boolean
+}
+
+export type ProgressCallback = (status: CompactionStatus) => void
+
+// ── Constants ──
+
+/** Timeout in ms after which we consider compaction "stuck" */
+const STUCK_TIMEOUT_MS = 30_000
+
+/** Max retries for summarizer API calls */
+const MAX_SUMMARIZER_RETRIES = 3
+
+/** Retry delay in ms between summarizer attempts */
+const RETRY_DELAY_MS = 2_000
+
+// ── Tracker ──
+
+export class CompactionProgressTracker {
+  private callback: ProgressCallback | null = null
+  private status: CompactionStatus
+  private startTime = 0
+  private lastProgressTime = 0
+
+  constructor(messagesBefore: number, tokensBefore: number) {
+    this.status = {
+      phase: 'microcompact',
+      message: 'Starting compaction...',
+      percent: 0,
+      messagesBefore,
+      messagesAfter: messagesBefore,
+      tokensBefore,
+      tokensAfter: tokensBefore,
+      elapsedMs: 0,
+      retryCount: 0,
+      retrying: false,
+      stuck: false,
+    }
+    this.startTime = Date.now()
+    this.lastProgressTime = Date.now()
+  }
+
+  /** Register a UI callback for progress updates. */
+  onProgress(cb: ProgressCallback): void {
+    this.callback = cb
+  }
+
+  /** Update phase with new values. */
+  update(partial: {
+    phase?: CompactionPhase
+    message?: string
+    percent?: number
+    messagesAfter?: number
+    tokensAfter?: number
+    retrying?: boolean
+  }): void {
+    if (partial.phase !== undefined) this.status.phase = partial.phase
+    if (partial.message !== undefined) this.status.message = partial.message
+    if (partial.percent !== undefined) this.status.percent = partial.percent
+    if (partial.messagesAfter !== undefined) this.status.messagesAfter = partial.messagesAfter
+    if (partial.tokensAfter !== undefined) this.status.tokensAfter = partial.tokensAfter
+    if (partial.retrying !== undefined) this.status.retrying = partial.retrying
+
+    this.status.elapsedMs = Date.now() - this.startTime
+
+    // Check for stuck detection
+    if (this.status.phase !== 'complete') {
+      const timeSinceProgress = Date.now() - this.lastProgressTime
+      this.status.stuck = timeSinceProgress > STUCK_TIMEOUT_MS
+    }
+
+    this.emit()
+  }
+
+  /** Mark current retry attempt. */
+  onRetry(attempt: number): void {
+    this.status.retryCount = attempt
+    this.status.retrying = true
+    this.emit()
+  }
+
+  /** Mark retry as complete (success or giving up). */
+  onRetryComplete(): void {
+    this.status.retrying = false
+    this.lastProgressTime = Date.now()
+    this.status.stuck = false
+    this.emit()
+  }
+
+  /** Mark compaction as complete. */
+  complete(messagesAfter: number, tokensAfter: number): void {
+    this.status.phase = 'complete'
+    this.status.percent = 100
+    this.status.messagesAfter = messagesAfter
+    this.status.tokensAfter = tokensAfter
+    this.status.message = `Compaction complete: ${this.status.messagesBefore} → ${messagesAfter} messages`
+    this.status.elapsedMs = Date.now() - this.startTime
+    this.emit()
+  }
+
+  /** Get current status. */
+  getStatus(): CompactionStatus {
+    return { ...this.status }
+  }
+
+  /** Generate a compact summary string for CLI display. */
+  getSummary(): string {
+    const s = this.status
+    const elapsed = (s.elapsedMs / 1000).toFixed(1)
+    const stuckHint = s.stuck ? ' (stalled — press Esc to cancel)' : ''
+    const retryHint = s.retrying ? ` [retry ${s.retryCount}/${MAX_SUMMARIZER_RETRIES}...]` : ''
+    const pct = s.percent >= 0 ? ` ${s.percent}%` : ''
+    return `🔄 [${s.phase}]${pct} ${s.message}${retryHint}${stuckHint} (${elapsed}s)`
+  }
+
+  private emit(): void {
+    if (this.callback) {
+      try {
+        this.callback(this.getStatus())
+      } catch {
+        // UI callback failure shouldn't block compaction
+      }
+    }
+  }
+
+  // ── Static helpers ──
+
+  /** Retry a summarizer call with backoff and progress tracking. */
+  static async retrySummarizer(
+    summarizer: () => Promise<string>,
+    tracker: CompactionProgressTracker,
+    messagesToSummarize: number,
+  ): Promise<string> {
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= MAX_SUMMARIZER_RETRIES; attempt++) {
+      try {
+        tracker.update({
+          message: `Summarizing ${messagesToSummarize} messages${attempt > 1 ? ` (attempt ${attempt}/${MAX_SUMMARIZER_RETRIES})` : ''}...`,
+          percent: 30 + attempt * 20,
+          retrying: attempt > 1,
+        })
+
+        const result = await summarizer()
+        tracker.onRetryComplete()
+        return result
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err))
+
+        if (attempt < MAX_SUMMARIZER_RETRIES) {
+          tracker.onRetry(attempt)
+          // Wait before retry
+          await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS))
+          tracker.onRetryComplete()
+        }
+      }
+    }
+
+    tracker.update({
+      message: `Summarization failed after ${MAX_SUMMARIZER_RETRIES} attempts — falling back to truncation`,
+      percent: 60,
+    })
+
+    throw lastError ?? new Error('Summarization failed')
+  }
+}

package/src/core/context-compact.ts

@@ -1,5 +1,6 @@
 import type { ContextManager, Summarizer } from './context'
 import { snipMessages } from './context-snip'
+import { CompactionProgressTracker } from './compaction-progress'
 
 /**
  * Layer 3: Reactive Compact — API-based summarization.
@@ -20,33 +21,85 @@ function getKeepRecent(contextWindow: number): number {
   return Math.max(20, Math.floor(contextWindow / 12500))
 }
 
+export interface CompactResult {
+  /** Messages before compaction */
+  beforeCount: number
+  /** Messages after compaction */
+  afterCount: number
+  /** Whether compaction was actually performed */
+  compacted: boolean
+  /** Progress summary for display */
+  summary: string
+}
+
 export async function reactiveCompact(
   context: ContextManager,
   summarizer: Summarizer,
   heading: string,
   keepRecent?: number,
-): Promise<void> {
+): Promise<CompactResult> {
   // Use explicit override, or adaptive default based on context window
   const effectiveKeepRecent = keepRecent ?? getKeepRecent(context.getMaxTokens())
   const messages = context.getMessages()
+  const tokensBefore = context.getEstimatedTokens()
 
-  if (messages.length <= effectiveKeepRecent + 4) return
+  if (messages.length <= effectiveKeepRecent + 4) {
+    return {
+      beforeCount: messages.length,
+      afterCount: messages.length,
+      compacted: false,
+      summary: `Context has ${messages.length} messages — no compaction needed (threshold: ${effectiveKeepRecent + 4}).`,
+    }
+  }
+
+  // ── Progress tracker ──
+  const tracker = new CompactionProgressTracker(messages.length, tokensBefore)
+  tracker.update({ phase: 'snip', message: 'Snipping empty pairs...', percent: 5 })
 
   // First, run snip to remove empty pairs
   const { messages: snipped } = snipMessages(messages)
+  tracker.update({
+    phase: 'snip',
+    message: `Snipped ${messages.length - snipped.length} empty pairs`,
+    percent: 15,
+    messagesAfter: snipped.length,
+  })
 
-  if (snipped.length <= effectiveKeepRecent + 4) return
+  if (snipped.length <= effectiveKeepRecent + 4) {
+    const afterCount = snipped.length
+    tracker.complete(afterCount, tokensBefore)
+    return {
+      beforeCount: messages.length,
+      afterCount,
+      compacted: true,
+      summary: `Snip-only: ${messages.length} → ${afterCount} messages (removed ${messages.length - afterCount} empty pairs).`,
+    }
+  }
 
   // Split: old messages to summarize, recent messages to keep
   const toSummarize = snipped.slice(0, -effectiveKeepRecent)
   const toKeep = snipped.slice(-effectiveKeepRecent)
 
-  // Generate summary
+  tracker.update({
+    phase: 'reactive-compact',
+    message: `Summarizing ${toSummarize.length} messages...`,
+    percent: 20,
+  })
+
+  // Generate summary with retry logic
   let summary: string
   try {
-    summary = await summarizer(toSummarize, heading)
+    summary = await CompactionProgressTracker.retrySummarizer(
+      () => summarizer(toSummarize, heading),
+      tracker,
+      toSummarize.length,
+    )
   } catch {
     // On summarizer failure, do a simple truncation
+    tracker.update({
+      message: `Summarizer unavailable — truncating to last ${effectiveKeepRecent} messages.`,
+      percent: 80,
+    })
     summary = `Earlier conversation (${toSummarize.length} messages) omitted due to context limits.`
   }
 
@@ -56,5 +109,16 @@ export async function reactiveCompact(
     content: `[Earlier conversation summary — ${heading}]: ${summary.slice(0, 8000)}`,
   }
 
-  context.replaceMessages([summaryMsg, ...toKeep])
+  const newMessages = [summaryMsg, ...toKeep]
+  context.replaceMessages(newMessages)
+
+  const tokensAfter = context.getEstimatedTokens()
+  tracker.complete(newMessages.length, tokensAfter)
+
+  return {
+    beforeCount: messages.length,
+    afterCount: newMessages.length,
+    compacted: true,
+    summary: tracker.getSummary(),
+  }
 }

package/src/core/context-drain.ts

@@ -1,4 +1,5 @@
 import type { ContextManager } from './context'
+import type { CompactionProgressTracker } from './compaction-progress'
 
 const MINIMAL_KEEP = 5
 let drainLevel = 0
@@ -12,22 +13,62 @@ let drainLevel = 0
  * 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.
+ * Returns drain result with progress summary.
  */
-export async function emergencyDrain(context: ContextManager): Promise<boolean> {
+export interface DrainResult {
+  /** Whether recovery was possible */
+  recovered: boolean
+  /** Messages before drain */
+  beforeCount: number
+  /** Messages after drain */
+  afterCount: number
+  /** Current drain level */
+  level: number
+  /** Human-readable summary */
+  summary: string
+}
+
+export async function emergencyDrain(
+  context: ContextManager,
+  progress?: CompactionProgressTracker,
+): Promise<DrainResult> {
   const messages = context.getMessages()
 
   if (messages.length <= MINIMAL_KEEP) {
-    return false // Already minimal, cannot drain further
+    return {
+      recovered: false,
+      beforeCount: messages.length,
+      afterCount: messages.length,
+      level: drainLevel,
+      summary: `Cannot drain further: already at minimal ${messages.length} messages.`,
+    }
   }
 
+  progress?.update({
+    phase: 'emergency-drain',
+    message: `Emergency drain level ${drainLevel + 1}: recovering from 413 error...`,
+    percent: 50,
+  })
+
   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
+    progress?.update({
+      phase: 'emergency-drain',
+      message: `Drain level 1: dropped ${messages.length - keepCount} messages (${messages.length} → ${keepCount})`,
+      percent: 80,
+      messagesAfter: keepCount,
+    })
+    return {
+      recovered: true,
+      beforeCount: messages.length,
+      afterCount: keepCount,
+      level: drainLevel,
+      summary: `Emergency drain level 1: ${messages.length} → ${keepCount} messages (dropped earliest 50%).`,
+    }
   }
 
   // Subsequent attempts: keep only system + last MINIMAL_KEEP messages
@@ -37,7 +78,7 @@ export async function emergencyDrain(context: ContextManager): Promise<boolean>
   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.]`,
+      content: `[Emergency context drain level ${drainLevel + 1}: ${messages.length - MINIMAL_KEEP} earlier messages discarded due to token limit.]`,
     }
     context.replaceMessages([summaryMsg, ...kept])
   } else {
@@ -45,10 +86,28 @@ export async function emergencyDrain(context: ContextManager): Promise<boolean>
   }
 
   drainLevel++
-  return true
+  progress?.update({
+    phase: 'emergency-drain',
+    message: `Drain level ${drainLevel}: ${messages.length} → ${kept.length} messages`,
+    percent: 90,
+    messagesAfter: kept.length,
+  })
+
+  return {
+    recovered: true,
+    beforeCount: messages.length,
+    afterCount: kept.length,
+    level: drainLevel,
+    summary: `Emergency drain level ${drainLevel}: ${messages.length} → ${kept.length} messages.`,
+  }
 }
 
 /** Reset drain level (call at session start). */
 export function resetDrainLevel(): void {
   drainLevel = 0
 }
+
+/** Get current drain level for display. */
+export function getDrainLevel(): number {
+  return drainLevel
+}

package/src/core/context.ts

@@ -124,8 +124,13 @@ export class ContextManager {
     return this.estimatedTokens > this.config.maxTokens * this.config.compactionThreshold
   }
 
-  async compact(heading: string): Promise<void> {
-    if (this.messages.length <= 30) return
+  async compact(heading: string): Promise<{ before: number; after: number }> {
+    const beforeMsgs = this.messages.length
+    const beforeTokens = this.estimatedTokens
+
+    if (this.messages.length <= 30) {
+      return { before: beforeTokens, after: beforeTokens }
+    }
 
     const keep = 20
     const toDrop = this.messages.slice(0, -keep)
@@ -155,6 +160,8 @@ export class ContextManager {
         typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
       )
     }
+
+    return { before: beforeTokens, after: this.estimatedTokens }
   }
 
   getEstimatedTokens(): number {
@@ -266,11 +273,11 @@ export class ContextManager {
    */
   async on413Error(): Promise<boolean> {
     const result = await emergencyDrain(this)
-    if (result) {
+    if (result.recovered) {
       this.compactionStats.drainCount++
       this.compactionStats.lastCompaction = new Date()
     }
-    return result
+    return result.recovered
   }
 
   // ── Forced compaction (e.g. /compact command) ──

package/src/core/engine.ts

@@ -55,6 +55,8 @@ export class QueryEngine {
   private _preflightChecker?: PreFlightChecker
   private _autoCorrector?: AutoCorrector
   private _metaRuleEngine?: MetaRuleEngine
+  /** Files read this session — tracks what the Read tool has loaded */
+  private readFiles = new Set<string>()
   private goal?: string
   private maxGoalLoops = 20
   private lastAssistantContent?: string
@@ -158,6 +160,11 @@ export class QueryEngine {
     this.hookEngine = hooks
   }
 
+  /** Get the registered hook engine (for health inspection). */
+  getHookEngine(): HookEngine | undefined {
+    return this.hookEngine
+  }
+
   /** Register the artifact server for tool context. */
   setArtifactServer(server: ArtifactServer): void {
     this.artifactServer = server
@@ -943,6 +950,7 @@ export class QueryEngine {
         backgroundAgentRegistry: getBackgroundAgentRegistry(),
         permissionSystem: this.permission,
         ruleEngine: this.ruleEngine,
+        readFiles: this.readFiles,
       })
 
       // Track touched files for rules matching