@pellux/goodvibes-tui 0.18.4

package/src/runtime/compaction/lifecycle.ts

@@ -0,0 +1,167 @@
+/**
+ * lifecycle.ts
+ *
+ * Compaction lifecycle state machine for the compaction engine.
+ *
+ * Provides:
+ * - Valid transition map for the 9-state machine
+ * - Pure transition helpers (no side-effects)
+ * - Strategy selection logic based on trigger and token pressure
+ */
+
+import type { CompactionLifecycleState, CompactionStrategy, CompactionTrigger } from './types.ts';
+
+// ---------------------------------------------------------------------------
+// Transition map
+// ---------------------------------------------------------------------------
+
+/**
+ * Valid state transitions for the compaction lifecycle machine.
+ *
+ * Key   = current state
+ * Value = set of states reachable from current
+ */
+const VALID_TRANSITIONS: ReadonlyMap<
+  CompactionLifecycleState,
+  ReadonlySet<CompactionLifecycleState>
+> = new Map([
+  ['idle',               new Set<CompactionLifecycleState>(['checking_threshold'])],
+  ['checking_threshold', new Set<CompactionLifecycleState>(['microcompact', 'collapse', 'autocompact', 'reactive_compact', 'done', 'failed'])],
+  ['microcompact',       new Set<CompactionLifecycleState>(['boundary_commit', 'failed'])],
+  ['collapse',           new Set<CompactionLifecycleState>(['boundary_commit', 'failed'])],
+  ['autocompact',        new Set<CompactionLifecycleState>(['boundary_commit', 'failed'])],
+  ['reactive_compact',   new Set<CompactionLifecycleState>(['boundary_commit', 'failed'])],
+  ['boundary_commit',    new Set<CompactionLifecycleState>(['done', 'failed'])],
+  ['done',               new Set<CompactionLifecycleState>(['idle'])],
+  ['failed',             new Set<CompactionLifecycleState>(['idle'])],
+]);
+
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns whether a transition from `from` to `to` is valid.
+ */
+export function canTransition(
+  from: CompactionLifecycleState,
+  to: CompactionLifecycleState,
+): boolean {
+  return VALID_TRANSITIONS.get(from)?.has(to) ?? false;
+}
+
+/**
+ * Returns all states reachable from `from`.
+ */
+export function reachableFrom(
+  from: CompactionLifecycleState,
+): ReadonlySet<CompactionLifecycleState> {
+  return VALID_TRANSITIONS.get(from) ?? new Set();
+}
+
+/** Discriminated result of `applyTransition`. */
+export type TransitionResult =
+  | { ok: true;  state: CompactionLifecycleState }
+  | { ok: false; reason: string };
+
+/**
+ * Validates and applies a state transition.
+ *
+ * @returns `{ ok: true, state }` on success, `{ ok: false, reason }` on rejection.
+ */
+export function applyTransition(
+  current: CompactionLifecycleState,
+  target: CompactionLifecycleState,
+): TransitionResult {
+  if (canTransition(current, target)) {
+    return { ok: true, state: target };
+  }
+  return {
+    ok: false,
+    reason: `Invalid compaction transition: ${current} → ${target}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Terminal / operational helpers
+// ---------------------------------------------------------------------------
+
+/** Returns true if the state is a terminal completion state (done | failed). */
+export function isTerminal(state: CompactionLifecycleState): boolean {
+  return state === 'done' || state === 'failed';
+}
+
+/** Returns true if the state represents active compaction work in progress. */
+export function isCompacting(state: CompactionLifecycleState): boolean {
+  return (
+    state === 'microcompact' ||
+    state === 'collapse' ||
+    state === 'autocompact' ||
+    state === 'reactive_compact' ||
+    state === 'boundary_commit'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Strategy selection
+// ---------------------------------------------------------------------------
+
+/** Parameters for selecting a compaction strategy. */
+export interface StrategySelectionParams {
+  /** What triggered compaction. */
+  trigger: CompactionTrigger;
+  /** Estimated tokens currently in context. */
+  currentTokens: number;
+  /** Model context window size. */
+  contextWindow: number;
+  /** Whether a prompt-too-long error was the immediate cause. */
+  isPromptTooLong?: boolean;
+}
+
+/**
+ * Selects the appropriate compaction strategy based on trigger and token pressure.
+ *
+ * Selection priority:
+ * 1. `reactive`     — any prompt-too-long error (emergency, must shrink now)
+ * 2. `microcompact` — token pressure < 50% of context window (light touch)
+ * 3. `autocompact`  — token pressure 50–85% (standard auto-compaction)
+ * 4. `collapse`     — token pressure > 85% or manual trigger (aggressive shrink)
+ */
+export function selectStrategy(
+  params: StrategySelectionParams,
+): CompactionStrategy {
+  const { trigger, currentTokens, contextWindow, isPromptTooLong } = params;
+
+  if (isPromptTooLong === true || trigger === 'prompt_too_long') {
+    return 'reactive';
+  }
+
+  const pressure = currentTokens / contextWindow;
+
+  if (pressure < 0.5) {
+    return 'microcompact';
+  }
+  if (pressure < 0.85) {
+    return 'autocompact';
+  }
+  // High pressure or manual trigger — aggressive collapse
+  return 'collapse';
+}
+
+/**
+ * Maps a chosen CompactionStrategy to its corresponding lifecycle state.
+ */
+export function strategyToState(
+  strategy: CompactionStrategy,
+): CompactionLifecycleState {
+  switch (strategy) {
+    case 'microcompact': return 'microcompact';
+    case 'collapse':     return 'collapse';
+    case 'autocompact':  return 'autocompact';
+    case 'reactive':     return 'reactive_compact';
+    default: {
+      const _exhaustive: never = strategy;
+      throw new Error(`Unknown compaction strategy: ${_exhaustive}`);
+    }
+  }
+}

package/src/runtime/compaction/manager.ts

@@ -0,0 +1,474 @@
+/**
+ * manager.ts
+ *
+ * CompactionManager — orchestrates the full compaction lifecycle state machine.
+ *
+ * Responsibilities:
+ * - Gate all compaction behind the `session-compaction` feature flag
+ * - Drive state transitions (idle → checking_threshold → strategy → boundary_commit → done/failed)
+ * - Select and execute the appropriate compaction strategy
+ * - Create boundary commits with lineage tracking
+ * - Emit CompactionEvents at each transition
+ * - Expose the resume repair pipeline
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { RuntimeEventBus } from '../events/index.ts';
+import type { FeatureFlagManager } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/manager';
+import type { EmitterContext } from '../emitters/index.ts';
+import {
+  applyTransition,
+  selectStrategy,
+  strategyToState,
+} from './lifecycle.ts';
+import {
+  runMicrocompact,
+  runCollapse,
+  runAutocompact,
+  runReactive,
+  createBoundaryCommit,
+  validateBoundaryCommit,
+} from './strategies/index.ts';
+import { runResumeRepair } from './resume-repair.ts';
+import type {
+  BoundaryCommit,
+  CompactionLifecycleResult,
+  CompactionLifecycleState,
+  CompactionStrategy,
+  CompactionTrigger,
+  StrategyInput,
+  StrategyOutput,
+} from './types.ts';
+import type { ResumeRepairResult } from './types.ts';
+import {
+  emitCompactionCheck,
+  emitCompactionDone,
+  emitCompactionFailed,
+  emitCompactionBoundaryCommit,
+  emitCompactionMicrocompact,
+  emitCompactionCollapse,
+  emitCompactionAutocompact,
+  emitCompactionReactive,
+  emitCompactionQualityScore,
+  emitCompactionStrategySwitch,
+} from '../emitters/compaction.ts';
+import { computeQualityScore, escalateStrategy, LOW_QUALITY_THRESHOLD } from './quality-score.ts';
+import type { CompactionQualityScore } from './quality-score.ts';
+import type { ProviderMessage } from '../../providers/interface.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+// ---------------------------------------------------------------------------
+// Manager options
+// ---------------------------------------------------------------------------
+
+/** Options for constructing a CompactionManager. */
+export interface CompactionManagerOptions {
+  /** Session ID for event correlation. */
+  sessionId: string;
+  /** Runtime event bus for emitting CompactionEvents. */
+  bus: RuntimeEventBus;
+  /** Feature flag manager — used to gate on `session-compaction`. */
+  flags: FeatureFlagManager;
+  /** Model context window size (tokens). */
+  contextWindow: number;
+  /** Threshold fraction at which compaction is triggered (default: 0.75). */
+  thresholdFraction?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+
+/**
+ * CompactionManager — manages the full lifecycle of session context compaction.
+ *
+ * All compaction is gated behind the `session-compaction` feature flag.
+ * When the flag is disabled, `compact()` is a no-op and returns the original
+ * messages unchanged.
+ *
+ * Usage:
+ * ```ts
+ * const manager = createCompactionManager({ sessionId, bus, flags, contextWindow });
+ * const result = await manager.compact({ messages, tokenCount: 45000, trigger: 'auto' });
+ * ```
+ */
+export class CompactionManager {
+  private readonly _sessionId: string;
+  private readonly _bus: RuntimeEventBus;
+  private readonly _flags: FeatureFlagManager;
+  private readonly _contextWindow: number;
+  private readonly _thresholdFraction: number;
+
+  /** Current state machine state. */
+  private _state: CompactionLifecycleState = 'idle';
+
+  /** Most recent boundary commit (null until first successful compaction). */
+  private _lastCommit: BoundaryCommit | null = null;
+
+  /** Emitter context used for all event emissions. */
+  private readonly _ctx: EmitterContext;
+
+  constructor(opts: CompactionManagerOptions) {
+    this._sessionId = opts.sessionId;
+    this._bus = opts.bus;
+    this._flags = opts.flags;
+    this._contextWindow = opts.contextWindow;
+    this._thresholdFraction = opts.thresholdFraction ?? 0.75;
+    this._ctx = {
+      sessionId: opts.sessionId,
+      source: 'compaction-manager',
+      traceId: crypto.randomUUID(),
+    };
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /** Returns the current lifecycle state. */
+  get state(): CompactionLifecycleState {
+    return this._state;
+  }
+
+  /** Returns the most recent boundary commit, or null. */
+  get lastCommit(): BoundaryCommit | null {
+    return this._lastCommit;
+  }
+
+  /**
+   * Options for a compaction run.
+   */
+
+  /**
+   * Runs the compaction lifecycle for the given messages and trigger.
+   *
+   * If the `session-compaction` feature flag is disabled, returns the
+   * original messages unchanged with no events emitted.
+   *
+   * @param opts - Run options.
+   * @returns Lifecycle result, or null if gated/skipped.
+   */
+  async compact(opts: {
+    messages: ProviderMessage[];
+    tokenCount: number;
+    trigger: CompactionTrigger;
+    isPromptTooLong?: boolean;
+  }): Promise<CompactionLifecycleResult | null> {
+    // ── Feature flag gate ────────────────────────────────────────────────────
+    if (!this._flags.isEnabled('session-compaction')) {
+      logger.debug('[CompactionManager] session-compaction flag disabled; skipping', {
+        sessionId: this._sessionId,
+      });
+      return null;
+    }
+
+    const runStart = Date.now();
+    const { messages, tokenCount, trigger, isPromptTooLong } = opts;
+    const threshold = Math.floor(this._contextWindow * this._thresholdFraction);
+
+    // ── Transition: idle → checking_threshold ────────────────────────────────
+    this._transition('checking_threshold');
+
+    emitCompactionCheck(this._bus, this._ctx, {
+      sessionId: this._sessionId,
+      tokenCount,
+      threshold,
+    });
+
+    // ── Check threshold ──────────────────────────────────────────────────────
+    if (trigger === 'auto' && !isPromptTooLong && tokenCount < threshold) {
+      // Below threshold — go straight to done without compacting
+      this._transition('done');
+      this._transition('idle');
+      logger.debug('[CompactionManager] below threshold; no compaction needed', {
+        sessionId: this._sessionId,
+        tokenCount,
+        threshold,
+      });
+      return null;
+    }
+
+    // ── Select strategy ──────────────────────────────────────────────────────
+    let strategy = selectStrategy({
+      trigger,
+      currentTokens: tokenCount,
+      contextWindow: this._contextWindow,
+      isPromptTooLong,
+    });
+    const strategyState = strategyToState(strategy);
+
+    // ── Transition: checking_threshold → <strategy state> ────────────────────
+    this._transition(strategyState);
+
+    // ── Execute strategy ─────────────────────────────────────────────────────
+    let strategyOutput: StrategyOutput;
+    let qualityScore: CompactionQualityScore | null = null;
+    let strategySwitchReason: string | null = null;
+
+    const strategyInput: StrategyInput = {
+      sessionId: this._sessionId,
+      messages,
+      tokensBefore: tokenCount,
+      contextWindow: this._contextWindow,
+      strategy,
+      meta: isPromptTooLong !== undefined ? { isPromptTooLong } : undefined,
+    };
+
+    try {
+      strategyOutput = await this._runStrategy(strategy, strategyInput);
+    } catch (err) {
+      const error = summarizeError(err);
+      this._transition('failed');
+      emitCompactionFailed(this._bus, this._ctx, {
+        sessionId: this._sessionId,
+        strategy,
+        error,
+      });
+      this._transition('idle');
+      logger.error('[CompactionManager] strategy execution failed', {
+        sessionId: this._sessionId,
+        strategy,
+        error,
+      });
+      return null;
+    }
+
+    // ── Score quality and auto-switch if low ─────────────────────────────────
+    qualityScore = computeQualityScore(strategyInput, strategyOutput);
+
+    emitCompactionQualityScore(this._bus, this._ctx, {
+      sessionId: this._sessionId,
+      strategy,
+      score: qualityScore.score,
+      grade: qualityScore.grade,
+      compressionRatio: qualityScore.compressionRatio,
+      retentionScore: qualityScore.retentionScore,
+      isLowQuality: qualityScore.isLowQuality,
+      description: qualityScore.description,
+    });
+
+    if (qualityScore.isLowQuality) {
+      const escalated = escalateStrategy(strategy);
+      if (escalated !== strategy) {
+        const reason = `Quality score ${qualityScore.score.toFixed(2)} below threshold ${LOW_QUALITY_THRESHOLD}; escalating from ${strategy} to ${escalated}`;
+        strategySwitchReason = reason;
+
+        logger.warn('[CompactionManager] low quality score — switching strategy', {
+          sessionId: this._sessionId,
+          fromStrategy: strategy,
+          toStrategy: escalated,
+          score: qualityScore.score,
+          grade: qualityScore.grade,
+        });
+
+        emitCompactionStrategySwitch(this._bus, this._ctx, {
+          sessionId: this._sessionId,
+          fromStrategy: strategy,
+          toStrategy: escalated,
+          reason,
+          score: qualityScore.score,
+        });
+
+        // Force state to the escalated strategy state, bypassing normal transition
+        // validation. This is intentional: quality-correction reruns are not modelled
+        // in the standard state machine, and forcing the state allows _runStrategy to
+        // emit the correct strategy event while keeping lifecycle state consistent.
+        this._state = strategyToState(escalated);
+
+        const escalatedInput: StrategyInput = { ...strategyInput, strategy: escalated };
+        try {
+          const escalatedOutput = await this._runStrategy(escalated, escalatedInput);
+          // Re-score the escalated result
+          qualityScore = computeQualityScore(escalatedInput, escalatedOutput);
+          strategyOutput = escalatedOutput;
+          strategy = escalated;
+        } catch (err) {
+          const error = summarizeError(err);
+          logger.warn('[CompactionManager] escalated strategy also failed; using original output', {
+            sessionId: this._sessionId,
+            strategy: escalated,
+            error,
+          });
+          // Fall back to the original output — restore to the original strategy state
+          this._state = strategyToState(strategy);
+        }
+      } else {
+        // Already at ceiling strategy (collapse or reactive) — log but continue
+        logger.debug('[CompactionManager] low quality at ceiling strategy; no escalation possible', {
+          sessionId: this._sessionId,
+          strategy,
+          score: qualityScore.score,
+        });
+      }
+    }
+
+    // ── Transition: <strategy> → boundary_commit ─────────────────────────────
+    this._transition('boundary_commit');
+
+    // ── Create boundary commit ───────────────────────────────────────────────
+    const commit = createBoundaryCommit({
+      sessionId: this._sessionId,
+      strategyOutput,
+      parent: this._lastCommit,
+      tokensBefore: tokenCount,
+    });
+
+    const commitErrors = validateBoundaryCommit(commit);
+    if (commitErrors.length > 0) {
+      const error = commitErrors.join('; ');
+      this._transition('failed');
+      emitCompactionFailed(this._bus, this._ctx, {
+        sessionId: this._sessionId,
+        strategy,
+        error,
+      });
+      this._transition('idle');
+      logger.error('[CompactionManager] boundary commit validation failed', {
+        sessionId: this._sessionId,
+        errors: commitErrors,
+      });
+      return null;
+    }
+
+    emitCompactionBoundaryCommit(this._bus, this._ctx, {
+      sessionId: this._sessionId,
+      checkpointId: commit.checkpointId,
+    });
+
+    this._lastCommit = commit;
+
+    // ── Transition: boundary_commit → done ───────────────────────────────────
+    this._transition('done');
+    const durationMs = Date.now() - runStart;
+
+    emitCompactionDone(this._bus, this._ctx, {
+      sessionId: this._sessionId,
+      strategy,
+      tokensBefore: tokenCount,
+      tokensAfter: strategyOutput.tokensAfter,
+      durationMs,
+    });
+
+    // ── Transition: done → idle ───────────────────────────────────────────────
+    this._transition('idle');
+
+    return {
+      sessionId: this._sessionId,
+      strategy,
+      tokensBefore: tokenCount,
+      tokensAfter: strategyOutput.tokensAfter,
+      durationMs,
+      commit,
+      messages: strategyOutput.messages,
+      warnings: strategyOutput.warnings,
+      qualityScore,
+      strategySwitchReason,
+    };
+  }
+
+  /**
+   * Runs the session resume repair pipeline on the last boundary commit.
+   *
+   * If no commit exists, returns a result with the original messages and
+   * a warning action.
+   *
+   * @param overrideCommit - Optional commit to repair (defaults to lastCommit).
+   * @returns ResumeRepairResult.
+   */
+  repair(
+    overrideCommit?: BoundaryCommit,
+  ): ResumeRepairResult {
+    const commit = overrideCommit ?? this._lastCommit;
+    if (!commit) {
+      return {
+        sessionId: this._sessionId,
+        repaired: false,
+        actions: [
+          {
+            kind: 'no_commit',
+            description: 'No boundary commit available; nothing to repair.',
+            severity: 'info',
+          },
+        ],
+        messages: [],
+        safeToResume: false,
+        failReason: 'No boundary commit available for repair.',
+      };
+    }
+    return runResumeRepair({ commit });
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Executes the selected strategy and emits the corresponding domain event.
+   */
+  private async _runStrategy(
+    strategy: CompactionStrategy,
+    input: StrategyInput,
+  ): Promise<StrategyOutput> {
+    switch (strategy) {
+      case 'microcompact': {
+        const output = runMicrocompact(input);
+        emitCompactionMicrocompact(this._bus, this._ctx, {
+          sessionId: this._sessionId,
+          turnCount: input.messages.length,
+          tokensBefore: input.tokensBefore,
+          tokensAfter: output.tokensAfter,
+        });
+        return output;
+      }
+      case 'collapse': {
+        const output = runCollapse(input);
+        emitCompactionCollapse(this._bus, this._ctx, {
+          sessionId: this._sessionId,
+          messageCount: input.messages.length,
+          tokensBefore: input.tokensBefore,
+          tokensAfter: output.tokensAfter,
+        });
+        return output;
+      }
+      case 'autocompact': {
+        const output = runAutocompact(input);
+        emitCompactionAutocompact(this._bus, this._ctx, {
+          sessionId: this._sessionId,
+          strategy: 'autocompact',
+          tokensBefore: input.tokensBefore,
+          tokensAfter: output.tokensAfter,
+        });
+        return output;
+      }
+      case 'reactive': {
+        const output = runReactive(input);
+        emitCompactionReactive(this._bus, this._ctx, {
+          sessionId: this._sessionId,
+          tokenCount: input.tokensBefore,
+          limit: this._contextWindow,
+        });
+        return output;
+      }
+      default: {
+        const _exhaustive: never = strategy;
+        throw new Error(`Unknown compaction strategy: ${_exhaustive}`);
+      }
+    }
+  }
+
+  /**
+   * Applies a state transition, throwing if invalid.
+   * Invalid transitions are logged and treated as internal errors.
+   */
+  private _transition(target: CompactionLifecycleState): void {
+    const result = applyTransition(this._state, target);
+    if (!result.ok) {
+      logger.error('[CompactionManager] invalid state transition', {
+        from: this._state,
+        to: target,
+        reason: result.reason,
+        sessionId: this._sessionId,
+      });
+      // Force to failed to avoid being stuck in an inconsistent state
+      this._state = 'failed';
+      return;
+    }
+    this._state = result.state;
+  }
+}