@pellux/goodvibes-tui 0.18.4 → 0.18.9

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

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

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';