@pellux/goodvibes-tui 0.18.8 → 0.18.9

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

@@ -1,65 +1 @@
-/**
- * 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,
-  };
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/autocompact';

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

@@ -1,106 +1 @@
-/**
- * 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;
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/boundary-commit';

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

@@ -1,90 +1 @@
-/**
- * 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 '';
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/collapse';

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

@@ -1,23 +1 @@
-/**
- * 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';
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/index';

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

@@ -1,74 +1 @@
-/**
- * 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,
-  };
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/microcompact';

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

@@ -1,89 +1 @@
-/**
- * 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,
-  };
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/strategies/reactive';

package/src/runtime/compaction/types.ts

@@ -1,221 +1 @@
-/**
- * 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;
-}
+export * from '@pellux/goodvibes-sdk/platform/runtime/compaction/types';