@pellux/goodvibes-tui 0.18.4

package/src/runtime/compaction/quality-score.ts

@@ -0,0 +1,279 @@
+/**
+ * quality-score.ts
+ *
+ * Compaction quality scoring — evaluates the output of a compaction strategy
+ * by combining compression ratio and semantic retention signals.
+ *
+ * Score range: 0.0 (worst) → 1.0 (best)
+ * Auto-switch threshold: scores below LOW_QUALITY_THRESHOLD trigger a strategy
+ * escalation to the next more-aggressive strategy.
+ */
+
+import type { StrategyInput, StrategyOutput, CompactionStrategy } from './types.ts';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Compaction runs scoring below this value are considered low-quality and
+ * trigger an automatic strategy switch.
+ */
+export const LOW_QUALITY_THRESHOLD = 0.4;
+
+/**
+ * Keywords that indicate a message is a compaction handoff/summary note.
+ */
+const HANDOFF_MARKERS = ['[Session', 'compaction', 'collapsed', 'summarized', 'condensed', 'context window'] as const;
+
+/**
+ * Weight given to compression ratio in the composite score (0–1).
+ * The remainder is allocated to semantic retention.
+ */
+const COMPRESSION_WEIGHT = 0.55;
+
+/**
+ * Weight given to semantic retention signals in the composite score (0–1).
+ */
+const RETENTION_WEIGHT = 0.45;
+
+/**
+ * Minimum meaningful compression ratio. A run with zero or negative compression
+ * scores 0 on the compression axis.
+ */
+const MIN_COMPRESSION_RATIO = 0;
+
+/**
+ * Compression ratio above which the compression dimension is fully saturated.
+ * Anything at or above this (e.g. 80% reduction) receives a perfect compression score.
+ */
+const MAX_COMPRESSION_RATIO = 0.8;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Letter grade derived from the composite quality score. */
+export type CompactionQualityGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+
+/** Semantic retention signals evaluated during scoring. */
+export interface SemanticRetentionSignals {
+  /** At least one handoff/summary message is present in the output. */
+  hasHandoff: boolean;
+  /** Output contains non-trivial content (not just a blank handoff note). */
+  hasNonTrivialContent: boolean;
+  /** The output message count is a reasonable fraction of the input. */
+  messageCountSane: boolean;
+  /** The output token count is positive. */
+  positiveTokenCount: boolean;
+}
+
+/** Full quality score breakdown for a compaction run. */
+export interface CompactionQualityScore {
+  /** Fraction of tokens removed: (tokensBefore - tokensAfter) / tokensBefore. */
+  compressionRatio: number;
+  /** Normalised compression dimension score (0–1). */
+  compressionScore: number;
+  /** Semantic retention dimension score (0–1). */
+  retentionScore: number;
+  /** Composite quality score: weighted sum of compression + retention (0–1). */
+  score: number;
+  /** Letter grade derived from score. */
+  grade: CompactionQualityGrade;
+  /** Individual semantic retention signals. */
+  signals: SemanticRetentionSignals;
+  /** True when score < LOW_QUALITY_THRESHOLD and strategy escalation should occur. */
+  isLowQuality: boolean;
+  /** Human-readable description of the score for diagnostics. */
+  description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts plain text content from a provider message.
+ */
+function extractTextContent(msg: StrategyOutput['messages'][number]): string {
+  if (typeof msg.content === 'string') return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+      .map((b) => b.text)
+      .join(' ');
+  }
+  return '';
+}
+
+/**
+ * Evaluates the semantic retention signals from a strategy output.
+ *
+ * These are lightweight structural checks — no LLM call required.
+ */
+function evaluateSemanticRetention(
+  input: StrategyInput,
+  output: StrategyOutput,
+): SemanticRetentionSignals {
+  const hasHandoff = output.messages.some((m) => {
+    const content = extractTextContent(m);
+    return HANDOFF_MARKERS.some((marker) => content.includes(marker));
+  });
+
+  const hasNonTrivialContent = output.messages.some((m) => {
+    const text = extractTextContent(m);
+    // Non-trivial means more than just whitespace, and longer than a minimal fragment
+    return text.trim().length > 20;
+  });
+
+  // Sane if output has at least 1 message and doesn't exceed input count
+  const messageCountSane =
+    output.messages.length >= 1 &&
+    output.messages.length <= input.messages.length;
+
+  const positiveTokenCount = output.tokensAfter > 0;
+
+  return {
+    hasHandoff,
+    hasNonTrivialContent,
+    messageCountSane,
+    positiveTokenCount,
+  };
+}
+
+/**
+ * Scores the semantic retention dimension as a 0–1 value.
+ *
+ * Each signal contributes equally. Missing signals reduce the score.
+ */
+function scoreRetention(signals: SemanticRetentionSignals): number {
+  const checks = [
+    signals.hasHandoff,
+    signals.hasNonTrivialContent,
+    signals.messageCountSane,
+    signals.positiveTokenCount,
+  ];
+  return checks.filter(Boolean).length / checks.length;
+}
+
+/**
+ * Normalises a raw compression ratio to a 0–1 score.
+ *
+ * A ratio of 0 (no reduction) → score 0.
+ * A ratio at MAX_COMPRESSION_RATIO (e.g. 80%) → score 1.
+ * Values above MAX_COMPRESSION_RATIO are clamped at 1.
+ * Negative ratios (output larger than input) are clamped at 0.
+ */
+function scoreCompression(ratio: number): number {
+  if (ratio <= MIN_COMPRESSION_RATIO) return 0;
+  const normalised = (ratio - MIN_COMPRESSION_RATIO) / (MAX_COMPRESSION_RATIO - MIN_COMPRESSION_RATIO);
+  return Math.min(1, Math.max(0, normalised));
+}
+
+/**
+ * Maps a composite score to a letter grade.
+ */
+function gradeScore(score: number): CompactionQualityGrade {
+  if (score >= 0.85) return 'A';
+  if (score >= 0.70) return 'B';
+  if (score >= 0.55) return 'C';
+  if (score >= LOW_QUALITY_THRESHOLD) return 'D';
+  return 'F';
+}
+
+/**
+ * Produces a human-readable diagnostic description for a quality score.
+ */
+export function describeScore(score: CompactionQualityScore): string {
+  const parts: string[] = [
+    `score=${score.score.toFixed(2)} (${score.grade})`,
+    `compression=${(score.compressionRatio * 100).toFixed(1)}%`,
+    `retention=${(score.retentionScore * 100).toFixed(0)}%`,
+  ];
+  if (score.isLowQuality) {
+    parts.push('LOW_QUALITY — strategy switch triggered');
+  }
+  return parts.join(', ');
+}
+
+/**
+ * Computes the quality score for a completed compaction strategy run.
+ *
+ * @param input  - The strategy input (pre-compaction state).
+ * @param output - The strategy output (post-compaction state).
+ * @returns A full CompactionQualityScore breakdown.
+ */
+function scoreCompactionOutput(
+  input: StrategyInput,
+  output: StrategyOutput,
+): CompactionQualityScore {
+  // Compression ratio: fraction of tokens removed
+  const compressionRatio =
+    input.tokensBefore > 0
+      ? Math.max(0, (input.tokensBefore - output.tokensAfter) / input.tokensBefore)
+      : 0;
+
+  const compressionScore = scoreCompression(compressionRatio);
+
+  const signals = evaluateSemanticRetention(input, output);
+  const retentionScore = scoreRetention(signals);
+
+  const score =
+    COMPRESSION_WEIGHT * compressionScore + RETENTION_WEIGHT * retentionScore;
+
+  const grade = gradeScore(score);
+  const isLowQuality = score < LOW_QUALITY_THRESHOLD;
+
+  return {
+    compressionRatio,
+    compressionScore,
+    retentionScore,
+    score,
+    grade,
+    signals,
+    isLowQuality,
+    description: '',  // filled below to avoid circular call
+  };
+}
+
+/**
+ * Computes the quality score with description filled in.
+ *
+ * Prefer this over `scoreCompactionOutput` for all public use.
+ */
+export function computeQualityScore(
+  input: StrategyInput,
+  output: StrategyOutput,
+): CompactionQualityScore {
+  const partial = scoreCompactionOutput(input, output);
+  const full: CompactionQualityScore = { ...partial, description: '' };
+  full.description = describeScore(full);
+  return full;
+}
+
+// ---------------------------------------------------------------------------
+// Strategy escalation
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the next more-aggressive strategy for escalation when quality is low.
+ *
+ * Escalation path:
+ *   microcompact → autocompact → collapse → collapse (ceiling)
+ *   reactive     → reactive (already maximum)
+ *
+ * @param current - The strategy that produced the low-quality result.
+ * @returns The escalated strategy to re-run with.
+ */
+export function escalateStrategy(current: CompactionStrategy): CompactionStrategy {
+  switch (current) {
+    case 'microcompact': return 'autocompact';
+    case 'autocompact':  return 'collapse';
+    case 'collapse':     return 'collapse'; // already most aggressive
+    case 'reactive':     return 'reactive'; // emergency — cannot escalate further
+    default: {
+      const _exhaustive: never = current;
+      throw new Error(`Unknown compaction strategy: ${_exhaustive}`);
+    }
+  }
+}

package/src/runtime/compaction/resume-repair.ts

@@ -0,0 +1,183 @@
+/**
+ * resume-repair.ts
+ *
+ * Session resume repair pipeline for the compaction engine.
+ *
+ * When a session is resumed from a saved boundary commit, this pipeline
+ * validates and repairs the compacted message list before it is handed
+ * to the active conversation context. Repairs are non-destructive and
+ * append-only — they never discard information without recording the
+ * action in the repair log.
+ *
+ * Repair checks (in order):
+ * 1. Empty message list                  → inject an empty-state handoff
+ * 2. Missing user message at position 0  → prepend synthetic user message
+ * 3. Context overflow (tokens > limit)   → truncate oldest messages
+ * 4. Corrupt content blocks              → strip non-serialisable blocks
+ */
+
+import type { ProviderMessage } from '../../providers/interface.ts';
+import { estimateTokens } from '../../core/compaction-types.ts';
+import type { BoundaryCommit } from './types.ts';
+import type { RepairAction, ResumeRepairResult } from './types.ts';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum tokens allowed in a resumed session before overflow truncation.
+ * Set conservatively at 80% of a typical 100K context window.
+ */
+const RESUME_MAX_TOKENS = 80_000;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the resume repair pipeline.
+ */
+export interface ResumeRepairOptions {
+  /** The boundary commit being resumed. */
+  commit: BoundaryCommit;
+  /** Maximum tokens allowed in the resumed session (default: RESUME_MAX_TOKENS). */
+  maxTokens?: number;
+}
+
+/**
+ * Runs the session resume repair pipeline on a boundary commit.
+ *
+ * Each check is run in sequence. If a repair is applied, the message list
+ * is updated in place for the next check. All repairs are recorded with
+ * their severity and description.
+ *
+ * @param options - Repair options.
+ * @returns A ResumeRepairResult with the (possibly repaired) messages and repair log.
+ */
+export function runResumeRepair(options: ResumeRepairOptions): ResumeRepairResult {
+  const { commit, maxTokens = RESUME_MAX_TOKENS } = options;
+  const { sessionId } = commit;
+  const actions: RepairAction[] = [];
+
+  // Work on a mutable copy
+  let messages: ProviderMessage[] = [...commit.messages] as ProviderMessage[];
+
+  // ── Check 1: Empty message list ───────────────────────────────────────────
+  if (messages.length === 0) {
+    actions.push({
+      kind: 'inject_empty_state_handoff',
+      description: 'Message list was empty; injected an empty-state handoff message.',
+      severity: 'warn',
+    });
+    messages = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: [
+              '[Session Resume — Empty State]',
+              `Session ${sessionId} was resumed with no prior messages.`,
+              'Starting fresh with no context.',
+            ].join('\n'),
+          },
+        ],
+      },
+    ];
+  }
+
+  // ── Check 2: First message must be from 'user' ────────────────────────────
+  if (messages[0].role !== 'user') {
+    actions.push({
+      kind: 'prepend_user_message',
+      description: `First message had role '${messages[0].role}'; prepended synthetic user message.`,
+      severity: 'warn',
+      meta: { originalFirstRole: messages[0].role },
+    });
+    const synthetic: ProviderMessage = {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: '[Session Resume] Continuing from a prior compacted session.',
+        },
+      ],
+    };
+    messages = [synthetic, ...messages];
+  }
+
+  // ── Check 3: Overflow truncation ─────────────────────────────────────────
+  let estimate = estimateTokens(JSON.stringify(messages));
+  if (estimate > maxTokens) {
+    const originalCount = messages.length;
+    while (messages.length > 1 && estimate > maxTokens) {
+      // Drop from position 1 (preserve the handoff at [0])
+      messages = [messages[0], ...messages.slice(2)];
+      estimate = estimateTokens(JSON.stringify(messages));
+    }
+    const dropped = originalCount - messages.length;
+    actions.push({
+      kind: 'truncate_overflow',
+      description: `Token estimate exceeded limit (${estimate}/${maxTokens}); dropped ${dropped} message(s).`,
+      severity: 'warn',
+      meta: { originalCount, droppedCount: dropped, tokenEstimate: estimate, maxTokens },
+    });
+  }
+
+  // ── Check 4: Strip non-serialisable content blocks ───────────────────────
+  const strippedCount = stripNonSerializableBlocks(messages);
+  if (strippedCount > 0) {
+    actions.push({
+      kind: 'strip_non_serializable',
+      description: `Stripped ${strippedCount} non-serialisable content block(s) from resumed messages.`,
+      severity: 'warn',
+      meta: { strippedCount },
+    });
+  }
+
+  const repaired = actions.length > 0;
+  const hasFatal = actions.some((a) => a.severity === 'error');
+
+  return {
+    sessionId,
+    repaired,
+    actions,
+    messages,
+    safeToResume: !hasFatal,
+    failReason: hasFatal
+      ? actions.find((a) => a.severity === 'error')?.description
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Repair helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strips content blocks that cannot be safely serialised to JSON.
+ *
+ * Returns the count of blocks stripped.
+ */
+function stripNonSerializableBlocks(messages: ProviderMessage[]): number {
+  let stripped = 0;
+  for (const msg of messages) {
+    // Check all roles for array content with non-serializable blocks
+    if (!Array.isArray(msg.content)) continue;
+    const before = msg.content.length;
+    const filtered = msg.content.filter((block) => {
+      try {
+        JSON.stringify(block);
+        return true;
+      } catch {
+        // Non-serialisable block — strip it
+        return false;
+      }
+    });
+    // Re-assign through a type-compatible user message mutation
+    (msg as { content: typeof filtered }).content = filtered;
+    stripped += before - filtered.length;
+  }
+  return stripped;
+}

package/src/runtime/compaction/strategies/autocompact.ts

@@ -0,0 +1,65 @@
+/**
+ * strategies/autocompact.ts
+ *
+ * Auto-compaction strategy for the session compaction pipeline.
+ *
+ * This strategy is used when token pressure is in the 50–85% range. It runs
+ * the full semantic compaction pipeline including section-based extraction,
+ * lineage tracking, and post-compaction validation.
+ */
+
+import type { ProviderMessage } from '../../../providers/interface.ts';
+import { estimateTokens } from '../../../core/compaction-types.ts';
+import type { StrategyInput, StrategyOutput } from '../types.ts';
+
+/**
+ * Applies automatic threshold-based compaction.
+ *
+ * This uses the standard compaction pipeline. If a registry-backed context
+ * summary is unavailable, it falls back to a structural compaction that keeps
+ * a wider recent-message window than microcompact.
+ *
+ * @param input - Strategy input.
+ * @returns Strategy output.
+ */
+export function runAutocompact(input: StrategyInput): StrategyOutput {
+  const startMs = Date.now();
+  const { messages, tokensBefore, strategy } = input;
+  const warnings: string[] = [];
+
+  // Keep the most recent 60% of messages by count, drop the oldest 40%
+  const keepCount = Math.max(1, Math.ceil(messages.length * 0.6));
+  const dropped = messages.length - keepCount;
+  const kept = messages.slice(-keepCount) as ProviderMessage[];
+
+  const handoff: ProviderMessage = {
+    role: 'user',
+    content: [
+      {
+        type: 'text',
+        text: [
+          '[Session Auto-Compaction]',
+          `${dropped} earlier message(s) compacted to reduce context size.`,
+          `Retaining the ${keepCount} most recent messages.`,
+          'Context window pressure was above threshold — automatic compaction applied.',
+        ].join('\n'),
+      },
+    ],
+  };
+
+  const compacted: ProviderMessage[] = [handoff, ...kept];
+  const tokensAfter = estimateTokens(JSON.stringify(compacted));
+
+  if (dropped === 0) {
+    warnings.push('autocompact: no messages were dropped; context may still be near limit');
+  }
+
+  return {
+    messages: compacted,
+    tokensAfter,
+    summary: `Auto-compaction: dropped ${dropped} messages (~${Math.round((1 - tokensAfter / tokensBefore) * 100)}% reduction).`,
+    strategy,
+    durationMs: Date.now() - startMs,
+    warnings,
+  };
+}

package/src/runtime/compaction/strategies/boundary-commit.ts

@@ -0,0 +1,106 @@
+/**
+ * strategies/boundary-commit.ts
+ *
+ * Boundary commit — persists a compacted snapshot as a named checkpoint with
+ * full lineage tracking for replay-safe session resumption.
+ *
+ * A boundary commit is always created after a successful compaction strategy
+ * run (microcompact, collapse, autocompact, or reactive). It forms the
+ * persistent anchor point that the resume-repair pipeline uses to restore
+ * a session from a corrupted or partial state.
+ *
+ * Lineage is append-only: each commit appends its own checkpointId to the
+ * parent's lineage array. This means any checkpoint can be sliced from any
+ * earlier commit without re-ordering.
+ */
+
+import type { BoundaryCommit } from '../types.ts';
+import type { StrategyOutput } from '../types.ts';
+
+/** Simple prefix for generated checkpoint IDs. */
+const CHECKPOINT_PREFIX = 'cpt';
+
+/**
+ * Generates a checkpoint ID using the current timestamp and a random suffix.
+ * Format: `cpt_<timestamp>_<random>`
+ */
+function generateCheckpointId(): string {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${CHECKPOINT_PREFIX}_${ts}_${rand}`;
+}
+
+/**
+ * Options for creating a boundary commit.
+ */
+export interface BoundaryCommitOptions {
+  /** Session ID this commit belongs to. */
+  sessionId: string;
+  /** The compaction strategy output to commit. */
+  strategyOutput: StrategyOutput;
+  /** Parent boundary commit, or null for the first commit. */
+  parent: BoundaryCommit | null;
+  /** Estimated token count before compaction (for audit). */
+  tokensBefore: number;
+}
+
+/**
+ * Creates a new BoundaryCommit from a strategy output.
+ *
+ * The new commit's lineage is derived by appending its own checkpointId
+ * to the parent's lineage (or starting a fresh lineage if `parent` is null).
+ *
+ * @param options - Commit options.
+ * @returns A fully populated BoundaryCommit.
+ */
+export function createBoundaryCommit(
+  options: BoundaryCommitOptions,
+): BoundaryCommit {
+  const { sessionId, strategyOutput, parent, tokensBefore } = options;
+  const checkpointId = generateCheckpointId();
+
+  const parentLineage: readonly string[] = parent?.lineage ?? [];
+  const lineage: readonly string[] = [...parentLineage, checkpointId];
+
+  return {
+    checkpointId,
+    sessionId,
+    createdAt: Date.now(),
+    strategy: strategyOutput.strategy,
+    parentCheckpointId: parent?.checkpointId ?? null,
+    lineage,
+    messages: strategyOutput.messages,
+    tokenCount: strategyOutput.tokensAfter,
+    tokensBefore,
+    summary: strategyOutput.summary,
+  };
+}
+
+/**
+ * Validates a BoundaryCommit for replay-safety.
+ *
+ * A commit is replay-safe if:
+ * - It has at least one message
+ * - Its lineage is ordered and contains its own checkpointId
+ * - Its tokenCount is positive
+ *
+ * @returns An array of validation error strings (empty = valid).
+ */
+export function validateBoundaryCommit(commit: BoundaryCommit): string[] {
+  const errors: string[] = [];
+
+  if (commit.messages.length === 0) {
+    errors.push('boundary_commit: no messages in checkpoint');
+  }
+  if (commit.tokenCount <= 0) {
+    errors.push('boundary_commit: tokenCount must be positive');
+  }
+  if (!commit.lineage.includes(commit.checkpointId)) {
+    errors.push('boundary_commit: checkpointId not found in lineage (lineage is corrupted)');
+  }
+  if (commit.lineage.length === 0) {
+    errors.push('boundary_commit: lineage is empty');
+  }
+
+  return errors;
+}