@pellux/goodvibes-tui 0.18.4

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

@@ -0,0 +1,90 @@
+/**
+ * strategies/collapse.ts
+ *
+ * Collapse strategy — full context collapse into a single compacted summary
+ * message. This is the most aggressive strategy, used when token pressure
+ * exceeds 85% or when manually triggered.
+ *
+ * All messages are reduced to a structured handoff that preserves:
+ * - The original task context (if known)
+ * - Key decisions and outcomes
+ * - The most recent user/assistant exchange
+ */
+
+import type { ProviderMessage } from '../../../providers/interface.ts';
+import { estimateTokens } from '../../../core/compaction-types.ts';
+import type { StrategyInput, StrategyOutput } from '../types.ts';
+
+/**
+ * Applies the collapse strategy: reduces all messages to a single structured
+ * handoff message that preserves the essential session context.
+ *
+ * @param input - Strategy input containing messages and context.
+ * @returns Strategy output with a single collapsed message.
+ */
+export function runCollapse(input: StrategyInput): StrategyOutput {
+  const startMs = Date.now();
+  const { messages, tokensBefore, sessionId, strategy } = input;
+  const warnings: string[] = [];
+
+  // Extract the last user/assistant exchange to preserve conversational context
+  const lastUserMsg = messages.findLast((m) => m.role === 'user');
+  const lastAssistantMsg = messages.findLast((m) => m.role === 'assistant');
+
+  const recentExchange: string[] = [];
+  if (lastUserMsg) {
+    const text = extractText(lastUserMsg);
+    if (text) recentExchange.push(`User: ${text.slice(0, 500)}`);
+  }
+  if (lastAssistantMsg) {
+    const text = extractText(lastAssistantMsg);
+    if (text) recentExchange.push(`Assistant: ${text.slice(0, 500)}`);
+  }
+
+  const handoffLines: string[] = [
+    `[Session Collapse — ${new Date().toISOString()}]`,
+    `Session: ${sessionId}`,
+    `${messages.length} message(s) collapsed to reduce context from ~${tokensBefore} tokens.`,
+    '',
+    '## Most Recent Exchange',
+    recentExchange.length > 0
+      ? recentExchange.join('\n')
+      : '(no user/assistant exchange found)',
+    '',
+    '## Context Note',
+    'The full conversation history has been collapsed. Please resume from the above context.',
+  ];
+
+  const handoff: ProviderMessage = {
+    role: 'user',
+    content: [{ type: 'text', text: handoffLines.join('\n') }],
+  };
+
+  const compacted: ProviderMessage[] = [handoff];
+  const tokensAfter = estimateTokens(JSON.stringify(compacted));
+
+  if (tokensAfter >= tokensBefore) {
+    warnings.push('collapse: compacted output is not smaller than input; possible data issue');
+  }
+
+  return {
+    messages: compacted,
+    tokensAfter,
+    summary: `Collapse: ${messages.length} messages → 1 handoff message (~${tokensAfter} tokens).`,
+    strategy,
+    durationMs: Date.now() - startMs,
+    warnings,
+  };
+}
+
+/** Extracts plain text from a ProviderMessage. */
+function extractText(msg: ProviderMessage): 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 '';
+}

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

@@ -0,0 +1,23 @@
+/**
+ * strategies/index.ts
+ *
+ * Barrel re-export for all compaction strategy modules.
+ */
+
+export { runMicrocompact } from './microcompact.ts';
+export { runCollapse } from './collapse.ts';
+export { runAutocompact } from './autocompact.ts';
+export { runReactive } from './reactive.ts';
+export { createBoundaryCommit, validateBoundaryCommit } from './boundary-commit.ts';
+export type { BoundaryCommitOptions } from './boundary-commit.ts';
+export {
+  computeQualityScore,
+  describeScore,
+  escalateStrategy,
+  LOW_QUALITY_THRESHOLD,
+} from '../quality-score.ts';
+export type {
+  CompactionQualityScore,
+  CompactionQualityGrade,
+  SemanticRetentionSignals,
+} from '../quality-score.ts';

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

@@ -0,0 +1,74 @@
+/**
+ * strategies/microcompact.ts
+ *
+ * Micro-compaction strategy — lightweight token reduction by summarising only
+ * the oldest turns in the conversation, preserving recent messages intact.
+ *
+ * This is the lowest-latency strategy: no LLM call, purely structural.
+ * It drops assistant/tool messages beyond a configurable "keep recent" window
+ * and prepends a short handoff note summarising what was dropped.
+ */
+
+import type { ProviderMessage } from '../../../providers/interface.ts';
+import { estimateTokens } from '../../../core/compaction-types.ts';
+import type { StrategyInput, StrategyOutput } from '../types.ts';
+
+/** Number of recent messages preserved without modification. */
+const DEFAULT_KEEP_RECENT = 20;
+
+/**
+ * Applies micro-compaction: keep the last N messages, drop earlier ones,
+ * and prepend a brief handoff note.
+ *
+ * @param input - Strategy input containing messages and context.
+ * @returns Strategy output with compacted messages and token estimates.
+ */
+export function runMicrocompact(input: StrategyInput): StrategyOutput {
+  const startMs = Date.now();
+  const { messages, tokensBefore, strategy } = input;
+
+  const keepRecent = DEFAULT_KEEP_RECENT;
+  const warnings: string[] = [];
+
+  if (messages.length <= keepRecent) {
+    // Nothing to compact — return messages unchanged
+    warnings.push('microcompact: message count within keep window; no reduction applied');
+    return {
+      messages: [...messages] as ProviderMessage[],
+      tokensAfter: tokensBefore,
+      summary: 'No compaction applied — message count within keep window.',
+      strategy,
+      durationMs: Date.now() - startMs,
+      warnings,
+    };
+  }
+
+  const kept = messages.slice(-keepRecent) as ProviderMessage[];
+  const droppedCount = messages.length - keepRecent;
+
+  const handoff: ProviderMessage = {
+    role: 'user',
+    content: [
+      {
+        type: 'text',
+        text: [
+          `[Session Micro-Compaction]`,
+          `${droppedCount} earlier message(s) were summarised to reduce context size.`,
+          `The conversation continues from the most recent ${keepRecent} messages.`,
+        ].join('\n'),
+      },
+    ],
+  };
+
+  const compacted: ProviderMessage[] = [handoff, ...kept];
+  const tokensAfter = estimateTokens(JSON.stringify(compacted));
+
+  return {
+    messages: compacted,
+    tokensAfter,
+    summary: `Micro-compaction: dropped ${droppedCount} messages, kept ${keepRecent} recent.`,
+    strategy,
+    durationMs: Date.now() - startMs,
+    warnings,
+  };
+}

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

@@ -0,0 +1,89 @@
+/**
+ * strategies/reactive.ts
+ *
+ * Reactive compaction strategy — emergency compaction triggered when the
+ * provider returns a prompt-too-long error.
+ *
+ * This strategy must shrink the context aggressively and immediately, with
+ * minimal latency. It uses a fixed-percentage drop that guarantees the
+ * compacted context fits within a conservative safety margin (50% of the
+ * context window).
+ */
+
+import type { ProviderMessage } from '../../../providers/interface.ts';
+import { estimateTokens } from '../../../core/compaction-types.ts';
+import type { StrategyInput, StrategyOutput } from '../types.ts';
+
+/**
+ * Target fraction of context window to fill after reactive compaction.
+ * Keeping below 50% provides a comfortable buffer for the next turn.
+ */
+const REACTIVE_TARGET_FRACTION = 0.45;
+
+/**
+ * Applies reactive compaction to handle a prompt-too-long error.
+ *
+ * Drops messages from the oldest end until the estimated token count
+ * falls below `contextWindow * REACTIVE_TARGET_FRACTION`, then prepends
+ * a reactive handoff note.
+ *
+ * @param input - Strategy input. `input.meta.limit` may carry the provider's
+ *               reported token limit for logging purposes.
+ * @returns Strategy output with a drastically reduced message list.
+ */
+export function runReactive(input: StrategyInput): StrategyOutput {
+  const startMs = Date.now();
+  const { messages, tokensBefore, contextWindow, strategy, meta } = input;
+  const warnings: string[] = [];
+
+  const targetTokens = Math.floor(contextWindow * REACTIVE_TARGET_FRACTION);
+  const providerLimit = typeof meta?.['limit'] === 'number' ? meta['limit'] : null;
+
+  // Pre-compute per-message token estimates, then use a running sum (O(n) not O(n²))
+  const perMessageTokens = (messages as ProviderMessage[]).map((m) =>
+    estimateTokens(JSON.stringify(m)),
+  );
+  let totalTokens = perMessageTokens.reduce((a, b) => a + b, 0);
+  let cutIndex = 0;
+  while (cutIndex < messages.length - 1 && totalTokens > targetTokens) {
+    totalTokens -= perMessageTokens[cutIndex];
+    cutIndex++;
+  }
+  const remaining: ProviderMessage[] = (messages as ProviderMessage[]).slice(cutIndex);
+
+  const droppedCount = messages.length - remaining.length;
+
+  if (droppedCount === 0) {
+    warnings.push('reactive: could not reduce context below target; context may still exceed limit');
+  }
+
+  const handoffLines: string[] = [
+    '[Reactive Compaction — Context Overflow Recovery]',
+    `Provider returned prompt-too-long${providerLimit !== null ? ` (limit: ${providerLimit} tokens)` : ''}.`,
+    `${droppedCount} message(s) dropped to recover from overflow.`,
+    `Estimated tokens before: ${tokensBefore}, target: ≤${targetTokens}.`,
+  ];
+
+  const handoff: ProviderMessage = {
+    role: 'user',
+    content: [{ type: 'text', text: handoffLines.join('\n') }],
+  };
+
+  const compacted: ProviderMessage[] = [handoff, ...remaining];
+  const tokensAfter = estimateTokens(JSON.stringify(compacted));
+
+  if (tokensAfter > targetTokens) {
+    warnings.push(
+      `reactive: final token estimate (${tokensAfter}) still exceeds target (${targetTokens})`,
+    );
+  }
+
+  return {
+    messages: compacted,
+    tokensAfter,
+    summary: `Reactive compaction: dropped ${droppedCount} messages to recover from overflow (~${tokensAfter} tokens remaining).`,
+    strategy,
+    durationMs: Date.now() - startMs,
+    warnings,
+  };
+}

package/src/runtime/compaction/types.ts

@@ -0,0 +1,221 @@
+/**
+ * types.ts
+ *
+ * Core types for the session compaction lifecycle engine.
+ *
+ * These are distinct from `src/core/compaction-types.ts` (the prompt compaction
+ * section types). This module defines the *lifecycle* layer: state machine
+ * states, strategies, boundary commits, and repair records.
+ */
+
+import type { ProviderMessage } from '../../providers/interface.ts';
+import type { CompactionQualityScore } from './quality-score.ts';
+
+export type { CompactionQualityScore };
+
+// ---------------------------------------------------------------------------
+// Compaction lifecycle states
+// ---------------------------------------------------------------------------
+
+/**
+ * All states of the compaction lifecycle state machine.
+ *
+ * Transition map:
+ *   idle → checking_threshold
+ *   checking_threshold → microcompact | collapse | autocompact | reactive_compact | done
+ *   microcompact → boundary_commit | failed
+ *   collapse → boundary_commit | failed
+ *   autocompact → boundary_commit | failed
+ *   reactive_compact → boundary_commit | failed
+ *   boundary_commit → done | failed
+ *   done → idle
+ *   failed → idle
+ */
+export type CompactionLifecycleState =
+  | 'idle'
+  | 'checking_threshold'
+  | 'microcompact'
+  | 'collapse'
+  | 'autocompact'
+  | 'reactive_compact'
+  | 'boundary_commit'
+  | 'done'
+  | 'failed';
+
+// ---------------------------------------------------------------------------
+// Strategy types
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union identifying which compaction strategy to apply.
+ *
+ * - `microcompact`  — lightweight summary of recent turns; lowest latency
+ * - `collapse`      — full context collapse into a single summary message
+ * - `autocompact`   — threshold-based automatic compaction
+ * - `reactive`      — emergency compaction triggered by prompt-too-long errors
+ */
+export type CompactionStrategy =
+  | 'microcompact'
+  | 'collapse'
+  | 'autocompact'
+  | 'reactive';
+
+// ---------------------------------------------------------------------------
+// Strategy input/output
+// ---------------------------------------------------------------------------
+
+/** Input passed to every compaction strategy. */
+export interface StrategyInput {
+  /** Session ID for event correlation. */
+  sessionId: string;
+  /** Messages at the time compaction is triggered. */
+  messages: readonly ProviderMessage[];
+  /** Estimated token count before compaction. */
+  tokensBefore: number;
+  /** Context window size for the current model. */
+  contextWindow: number;
+  /** Which strategy is being applied (for self-identification in results). */
+  strategy: CompactionStrategy;
+  /** Optional additional metadata from the trigger. */
+  meta?: Record<string, unknown>;
+}
+
+/** Output produced by every compaction strategy. */
+export interface StrategyOutput {
+  /** Compacted message list to replace the current conversation. */
+  messages: ProviderMessage[];
+  /** Estimated token count after compaction. */
+  tokensAfter: number;
+  /** Human-readable summary of what was compacted. */
+  summary: string;
+  /** Strategy that produced this output. */
+  strategy: CompactionStrategy;
+  /** Wall-clock duration for this strategy's execution. */
+  durationMs: number;
+  /** Any warnings or non-fatal issues encountered. */
+  warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Boundary commit
+// ---------------------------------------------------------------------------
+
+/**
+ * A boundary commit persists a compacted snapshot for replay-safe resumption.
+ *
+ * Each boundary commit stores:
+ * - A unique checkpoint ID
+ * - The compacted message slice (replay-safe: can be sliced from any prior state)
+ * - A lineage reference to its parent (or null for the root commit)
+ * - The strategy that produced this checkpoint
+ */
+export interface BoundaryCommit {
+  /** Unique monotonic checkpoint identifier (e.g. `cpt_<ulid>`). */
+  checkpointId: string;
+  /** Session ID this commit belongs to. */
+  sessionId: string;
+  /** Unix timestamp (ms) when this commit was created. */
+  createdAt: number;
+  /** Strategy that produced the compacted snapshot. */
+  strategy: CompactionStrategy;
+  /**
+   * Parent checkpoint ID in the lineage chain.
+   * `null` for the root commit (no prior compaction).
+   */
+  parentCheckpointId: string | null;
+  /**
+   * Ordered lineage of all prior checkpoint IDs from root to this commit.
+   * Used for replay-safe slicing — always append-only.
+   */
+  lineage: readonly string[];
+  /** The compacted messages at this boundary. */
+  messages: readonly ProviderMessage[];
+  /** Token count of the compacted messages. */
+  tokenCount: number;
+  /** Estimated token count before compaction (for audit). */
+  tokensBefore: number;
+  /** Human-readable summary stored with this checkpoint. */
+  summary: string;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle result
+// ---------------------------------------------------------------------------
+
+/**
+ * Result produced at the end of a complete compaction lifecycle run.
+ *
+ * Populated after transitioning through boundary_commit → done.
+ */
+export interface CompactionLifecycleResult {
+  /** Session ID this run was executed for. */
+  sessionId: string;
+  /** Strategy that was selected and executed. */
+  strategy: CompactionStrategy;
+  /** Tokens before compaction. */
+  tokensBefore: number;
+  /** Tokens after compaction. */
+  tokensAfter: number;
+  /** Total wall-clock duration from trigger to done. */
+  durationMs: number;
+  /** Boundary commit produced during this run (null if boundary_commit was skipped). */
+  commit: BoundaryCommit | null;
+  /** Compacted message list. */
+  messages: ProviderMessage[];
+  /** Strategy output warnings. */
+  warnings: string[];
+  /** Quality score for the strategy run (null when scoring was skipped). */
+  qualityScore: CompactionQualityScore | null;
+  /** Strategy switch reason if auto-escalation occurred (null otherwise). */
+  strategySwitchReason: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Trigger
+// ---------------------------------------------------------------------------
+
+/**
+ * What initiated the compaction lifecycle run.
+ *
+ * - `auto`        — threshold check determined compaction is needed
+ * - `manual`      — user or orchestrator explicitly requested compaction
+ * - `prompt_too_long` — reactive trigger from a provider prompt-too-long error
+ */
+export type CompactionTrigger = 'auto' | 'manual' | 'prompt_too_long';
+
+// ---------------------------------------------------------------------------
+// Resume repair
+// ---------------------------------------------------------------------------
+
+/**
+ * Severity of a repair action applied during session resume.
+ */
+export type RepairSeverity = 'info' | 'warn' | 'error';
+
+/** A single repair action applied during session resume. */
+export interface RepairAction {
+  /** Short identifier for this repair type (e.g. `'truncate_overflow'`). */
+  kind: string;
+  /** Human-readable description of what was repaired. */
+  description: string;
+  /** Severity classification. */
+  severity: RepairSeverity;
+  /** Optional metadata about what was changed. */
+  meta?: Record<string, unknown>;
+}
+
+/** Result of the session resume repair pipeline. */
+export interface ResumeRepairResult {
+  /** Session ID that was repaired. */
+  sessionId: string;
+  /** Whether any repairs were applied. */
+  repaired: boolean;
+  /** List of repair actions applied (empty if no repairs were needed). */
+  actions: RepairAction[];
+  /** Messages after repair (may be unchanged if no repairs were needed). */
+  messages: ProviderMessage[];
+  /** Whether the session is safe to resume after repair. */
+  safeToResume: boolean;
+  /** Human-readable reason if not safe to resume. */
+  failReason?: string;
+}

package/src/runtime/context.ts

@@ -0,0 +1,158 @@
+/**
+ * RuntimeContext — the composition root object returned by bootstrapRuntime().
+ *
+ * main.ts receives this and uses it to drive the render loop, input handling,
+ * and terminal lifecycle. The bootstrap owns initialization; main.ts owns
+ * the runtime loop.
+ */
+import type { ConversationManager } from '../core/conversation.ts';
+import type { Orchestrator } from '../core/orchestrator.ts';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools/registry';
+import type { PermissionManager } from '../permissions/manager.ts';
+import type { HookDispatcher } from '../hooks/dispatcher.ts';
+import type { FileStateCache } from '@pellux/goodvibes-sdk/platform/state/file-cache';
+import type { ProjectIndex } from '@pellux/goodvibes-sdk/platform/state/project-index';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import type { RuntimeStore } from './store/index.ts';
+import type { RuntimeEventBus } from './events/index.ts';
+import type { FeatureFlagManager } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/index';
+import type { SessionSnapshot } from './session-persistence.ts';
+import type { RuntimeServices } from './services.ts';
+import type { PanelHealthMonitor } from '@pellux/goodvibes-sdk/platform/runtime/perf/panel-health-monitor';
+import type { WorktreeRegistry } from './worktree/registry.ts';
+import type { SandboxSessionRegistry } from './sandbox/session-registry.ts';
+
+/**
+ * Mutable runtime state that may be changed by slash commands or model-picker events.
+ * Kept as a plain object so event handlers can close over it by reference.
+ *
+ * Named `MutableRuntimeState` to avoid a name collision with `RuntimeState` in
+ * `src/runtime/store/state.ts`.
+ */
+export interface MutableRuntimeState {
+  model: string;
+  provider: string;
+  debugMode: boolean;
+  systemPrompt: string;
+  /** Empty string if not configured. */
+  reasoningEffort: string;
+  sessionId: string;
+}
+
+/**
+ * Options accepted by bootstrapRuntime().
+ */
+export interface BootstrapOptions {
+  /** App-owned working directory for this runtime instance. */
+  workingDir: string;
+  /** App-owned home directory for this runtime instance. */
+  homeDirectory: string;
+  /** Explicit app-owned config manager for this runtime instance. */
+  configManager: import('../config/manager.ts').ConfigManager;
+  /**
+   * Callback invoked when the app should exit.
+   * If provided, commandContext.exit is wired during bootstrap.
+   * Otherwise main.ts binds the shell-owned exit bridge immediately after bootstrap returns.
+   */
+  exit?: () => void;
+}
+
+/**
+ * The fully-initialized runtime context produced by bootstrapRuntime().
+ *
+ * main.ts destructures this to obtain what it needs for the render loop
+ * and input handling.
+ */
+export interface RuntimeContext {
+  // ── Core subsystems ─────────────────────────────────────────────────
+
+  /**
+   * Typed domain event bus for new runtime subsystems.
+   */
+  runtimeBus: RuntimeEventBus;
+
+  /**
+   * Zustand vanilla store for domain state slices.
+   */
+  store: RuntimeStore;
+
+  /**
+   * App-scoped runtime services graph shared across adapters and shells.
+   */
+  services: RuntimeServices;
+
+  /**
+   * Feature flag and kill-switch manager.
+   * Gates runtime subsystems and release controls.
+   */
+  featureFlags: FeatureFlagManager;
+
+  // ── Managers ────────────────────────────────────────────────────────
+
+  /** Manages conversation history and message rendering. */
+  conversation: ConversationManager;
+
+  /** Controls tool execution approval flow. */
+  permissions: PermissionManager;
+
+  /** Registry of all registered tool implementations. */
+  toolRegistry: ToolRegistry;
+
+  // ── Provider ────────────────────────────────────────────────────────
+
+  /** Shared provider registry owned by the runtime services graph. */
+  providerRegistry: ProviderRegistry;
+
+  /** Shared panel-health monitor owned by the runtime services graph. */
+  panelHealthMonitor: PanelHealthMonitor;
+
+  /** Shared worktree registry owned by the runtime services graph. */
+  worktreeRegistry: WorktreeRegistry;
+
+  /** Shared sandbox session registry owned by the runtime services graph. */
+  sandboxSessionRegistry: SandboxSessionRegistry;
+
+  // ── Infrastructure ──────────────────────────────────────────────────
+
+  /** Fires lifecycle hooks registered by the user or plugins. */
+  hookDispatcher: HookDispatcher;
+
+  // ── State ───────────────────────────────────────────────────────────
+
+  /** File read/write cache shared across read/write/edit tools in a session. */
+  fileCache: FileStateCache;
+
+  /** Project-level file index shared across tools. */
+  projectIndex: ProjectIndex;
+
+  // ── Session ─────────────────────────────────────────────────────────
+
+  /** Unique identifier for this user session (hex, prefixed "user-"). */
+  sessionId: string;
+
+  /** True if a previous session was resumed at startup. */
+  isResumed: boolean;
+
+  // ── Mutable runtime state ───────────────────────────────────────────
+
+  /** Mutable model/provider/prompt state closed over by event handlers. */
+  runtime: MutableRuntimeState;
+
+  // ── Orchestrator ─────────────────────────────────────────────────────
+
+  /**
+   * Main LLM orchestrator. Drives the conversation loop, tool execution,
+   * streaming, and context compaction.
+   */
+  orchestrator: Orchestrator;
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  /**
+   * Logical shutdown: save session, fire hooks, stop background managers.
+   * Does NOT touch the terminal — main.ts owns terminal teardown.
+   *
+   * @param sessionData - Latest conversation data to persist.
+   */
+  shutdown: (sessionData: SessionSnapshot) => Promise<void>;
+}