@pellux/goodvibes-tui 0.18.4

package/src/core/compaction-sections.ts

@@ -0,0 +1,492 @@
+/**
+ * compaction-sections.ts
+ *
+ * Section builder functions for prompt compaction.
+ *
+ * Rule-based builders return CompactionSection | null directly.
+ * LLM-assisted builders return a string prompt to be sent to the LLM by the
+ * orchestrator; the caller assembles the section from the LLM response.
+ *
+ * Empty sections return null — the orchestrator omits them entirely (no header).
+ */
+
+import type { ProviderMessage, ContentPart } from '../providers/interface.ts';
+import type { AgentRecord } from '../tools/agent/index.ts';
+import type { WrfcChain } from '../agents/wrfc-types.ts';
+import type { ExecutionPlan, PlanItem } from '@pellux/goodvibes-sdk/platform/core/execution-plan';
+import type { CompactionSection, CompactionConfig, SessionMemory } from './compaction-types.ts';
+import { estimateTokens } from './compaction-types.ts';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Extract plain text from a ProviderMessage content field. */
+function extractText(content: string | ContentPart[]): string {
+  if (typeof content === 'string') return content;
+  return (content as ContentPart[])
+    .filter((p): p is { type: 'text'; text: string } => p.type === 'text')
+    .map((p) => p.text)
+    .join('');
+}
+
+/** Build a CompactionSection. Returns null if content is empty. */
+function makeSection(
+  id: string,
+  header: string,
+  content: string,
+): CompactionSection | null {
+  const trimmed = content.trim();
+  if (!trimmed) return null;
+  return {
+    id,
+    header,
+    content: trimmed,
+    tokens: estimateTokens(header + '\n' + trimmed),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Handoff header
+// ---------------------------------------------------------------------------
+
+/**
+ * buildHandoffHeader — always returns the mandatory handoff header.
+ * This is the first line of every compacted output.
+ */
+export function buildHandoffHeader(): CompactionSection {
+  const content =
+    'IMPORTANT: This session is not new! Context was compacted, please read the following for proper handoff so you may resume work!';
+  return {
+    id: 'handoff-header',
+    header: '',
+    content,
+    tokens: estimateTokens(content),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Session memories
+// ---------------------------------------------------------------------------
+
+/**
+ * buildSessionMemories — format pinned memories.
+ * Returns null if there are no memories.
+ */
+export function buildSessionMemories(
+  memories: SessionMemory[],
+): CompactionSection | null {
+  if (memories.length === 0) return null;
+  const lines = memories.map((m) => `- [${m.id}] ${m.text}`);
+  return makeSection(
+    'session-memories',
+    '## Session Memories (pinned)',
+    lines.join('\n'),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Current task
+// ---------------------------------------------------------------------------
+
+/**
+ * buildCurrentTask — one line stating what the user is currently doing.
+ * Uses plan title if a plan exists, otherwise falls back to the last user message.
+ */
+export function buildCurrentTask(
+  planTitle: string | null,
+  lastUserMessage: string | null,
+): CompactionSection | null {
+  const task =
+    planTitle ??
+    (lastUserMessage ? lastUserMessage.slice(0, 200).trim() : null);
+  if (!task) return null;
+  return makeSection('current-task', '## Current Task', task);
+}
+
+// ---------------------------------------------------------------------------
+// Running agents
+// ---------------------------------------------------------------------------
+
+/**
+ * buildRunningAgents — list agents in running or pending status.
+ * Includes WRFC chain ID, agent ID, and task (truncated to 80 chars).
+ * Returns null if no agents are running.
+ */
+export function buildRunningAgents(
+  agents: AgentRecord[],
+  chains: WrfcChain[],
+): CompactionSection | null {
+  const active = agents.filter(
+    (a) => a.status === 'running' || a.status === 'pending',
+  );
+  if (active.length === 0) return null;
+
+  // Build a map from agent ID to chain ID for quick lookup
+  const agentToChain = new Map<string, string>();
+  for (const chain of chains) {
+    for (const agentId of chain.allAgentIds) {
+      agentToChain.set(agentId, chain.id);
+    }
+  }
+
+  const lines = active.map((a) => {
+    const chainId = a.wrfcId ?? agentToChain.get(a.id) ?? 'no-chain';
+    const task = a.task.slice(0, 80).replace(/\n/g, ' ');
+    return `- ${chainId} | ${a.id} | ${task}`;
+  });
+
+  return makeSection('running-agents', '## Currently Running', lines.join('\n'));
+}
+
+// ---------------------------------------------------------------------------
+// Recent conversation gather
+// ---------------------------------------------------------------------------
+
+/**
+ * gatherRecentConversation — collect user/assistant messages backward from most
+ * recent, stopping when adding the next message would exceed maxTokens.
+ * Returns full messages only (no partial messages).
+ *
+ * The returned messages are raw — they will be further filtered by the LLM
+ * substance filter in the orchestrator.
+ */
+export function gatherRecentConversation(
+  messages: ProviderMessage[],
+  maxTokens = 3000,
+): ProviderMessage[] {
+  const eligible = messages.filter(
+    (m) => m.role === 'user' || m.role === 'assistant',
+  );
+
+  const gathered: ProviderMessage[] = [];
+  let tokenCount = 0;
+
+  // Work backward from most recent
+  for (let i = eligible.length - 1; i >= 0; i--) {
+    const msg = eligible[i];
+    const msgTokens = estimateTokens(extractText(msg.content));
+    if (tokenCount + msgTokens > maxTokens) break;
+    gathered.unshift(msg);
+    tokenCount += msgTokens;
+  }
+
+  return gathered;
+}
+
+// ---------------------------------------------------------------------------
+// LLM substance filter prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * buildToolResultsPrompt — build the prompt for LLM-assisted tool relevance extraction.
+ *
+ * The caller sends this to the LLM and uses the response as the section content.
+ */
+export function buildToolResultsPrompt(toolMessages: ProviderMessage[]): string {
+  if (toolMessages.length === 0) return '';
+
+  const parts: string[] = [
+    'From these tool call results, select the ones that are still relevant for ongoing work.',
+    'Include: file paths touched with what was done (created/edited/deleted), any error outputs',
+    'that have not been resolved, any build/test results.',
+    'Max 1,500 tokens. Use relative paths and short descriptions.',
+    '',
+    '--- TOOL RESULTS ---',
+    '',
+  ];
+
+  for (const msg of toolMessages) {
+    const text = extractText(msg.content);
+    if (text.trim()) {
+      parts.push(`[tool]: ${text.trim().slice(0, 2000)}`);
+      parts.push('');
+    }
+  }
+
+  parts.push('--- END TOOL RESULTS ---');
+  parts.push('');
+  parts.push('Provide a concise summary of relevant tool results now:');
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Recent conversation substance filter prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * buildConversationFilterPrompt — build the LLM prompt for filtering gathered
+ * recent messages for substance.
+ *
+ * The caller sends this to the LLM; the response replaces the raw gathered messages.
+ * Multi-turn coherence rule: keep user-assistant PAIRS.
+ */
+export function buildConversationFilterPrompt(
+  gatheredMessages: ProviderMessage[],
+): string {
+  if (gatheredMessages.length === 0) return '';
+
+  const parts: string[] = [
+    'From these recent messages, remove anything that does not advance the work:',
+    'short acknowledgments, agent count updates, repetitive system nudges, status confirmations.',
+    'Keep: instructions, planning, decisions, task assignments, requirement changes.',
+    'ALL user messages are high-priority — bias toward keeping them even if short.',
+    'Keep user-assistant pairs together: if you keep an assistant message, keep the user message that prompted it.',
+    'Return only the messages worth preserving, in original order.',
+    '',
+    '--- RECENT MESSAGES ---',
+    '',
+  ];
+
+  for (const msg of gatheredMessages) {
+    const text = extractText(msg.content);
+    if (text.trim()) {
+      parts.push(`[${msg.role}]: ${text.trim()}`);
+      parts.push('');
+    }
+  }
+
+  parts.push('--- END RECENT MESSAGES ---');
+  parts.push('');
+  parts.push('Return the filtered messages in the same [role]: content format:');
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Agent activity table
+// ---------------------------------------------------------------------------
+
+/**
+ * buildAgentActivityTable — rule-based table from WRFC chain data.
+ * One row per chain, most recent first. Skips intermediate reviews/fix cycles.
+ * Stops when adding the next row would exceed the token budget.
+ *
+ * Returns:
+ *   - section: the table section (or null if no chains)
+ *   - remainingChains: chains that did not fit in the table (for older summary)
+ */
+export function buildAgentActivityTable(
+  chains: WrfcChain[],
+  tokenBudget: number,
+): { section: CompactionSection | null; remainingChains: WrfcChain[] } {
+  if (chains.length === 0) {
+    return { section: null, remainingChains: [] };
+  }
+
+  // Sort most recent first
+  const sorted = [...chains].sort((a, b) => b.createdAt - a.createdAt);
+
+  const header = '## Agent Activity';
+  const tableHeader = '| Chain | Task | Scores | Result |\n|-------|------|--------|--------|';
+  const rows: string[] = [];
+  const included: WrfcChain[] = [];
+  const remaining: WrfcChain[] = [];
+
+  let tokensSoFar = estimateTokens(header + '\n' + tableHeader);
+
+  for (const chain of sorted) {
+    const task = chain.task.slice(0, 60).replace(/\n/g, ' ');
+    const scores =
+      chain.reviewScores.length > 0
+        ? chain.reviewScores.map((s) => s.toFixed(1)).join(' → ')
+        : '—';
+    const result = terminalResult(chain.state);
+    const row = `| ${chain.id.slice(0, 12)} | ${task} | ${scores} | ${result} |`;
+    const rowTokens = estimateTokens(row + '\n');
+
+    if (tokensSoFar + rowTokens > tokenBudget) {
+      remaining.push(chain);
+      // All further chains also go to remaining
+      const idx = sorted.indexOf(chain);
+      remaining.push(...sorted.slice(idx + 1));
+      break;
+    }
+
+    rows.push(row);
+    tokensSoFar += rowTokens;
+    included.push(chain);
+  }
+
+  if (rows.length === 0) {
+    return { section: null, remainingChains: sorted };
+  }
+
+  const content = tableHeader + '\n' + rows.join('\n');
+  const section = makeSection('agent-activity', header, content);
+  return { section, remainingChains: remaining };
+}
+
+/** Map WRFC chain state to display result. */
+function terminalResult(state: WrfcChain['state']): string {
+  switch (state) {
+    case 'passed': return 'PASSED';
+    case 'failed': return 'FAILED';
+    case 'committing': return 'IN_PROGRESS';
+    case 'gating': return 'IN_PROGRESS';
+    case 'awaiting_gates': return 'IN_PROGRESS';
+    case 'reviewing': return 'IN_PROGRESS';
+    case 'fixing': return 'IN_PROGRESS';
+    case 'engineering': return 'IN_PROGRESS';
+    case 'pending': return 'IN_PROGRESS';
+    default: return 'UNKNOWN';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Older agent summary prompt (LLM-assisted)
+// ---------------------------------------------------------------------------
+
+/**
+ * buildOlderAgentSummaryPrompt — build the prompt for LLM-assisted summary of
+ * agents that did not fit in the activity table.
+ *
+ * Returns empty string if no older chains.
+ */
+export function buildOlderAgentSummaryPrompt(olderChains: WrfcChain[]): string {
+  if (olderChains.length === 0) return '';
+
+  const parts: string[] = [
+    'Summarize what these agents accomplished in aggregate.',
+    'Focus on outcomes: what was built, fixed, reviewed. Max 500 tokens.',
+    '',
+    '--- OLDER AGENTS ---',
+    '',
+  ];
+
+  for (const chain of olderChains) {
+    const task = chain.task.slice(0, 200).replace(/\n/g, ' ');
+    const scores =
+      chain.reviewScores.length > 0
+        ? chain.reviewScores.map((s) => s.toFixed(1)).join(' → ')
+        : 'no scores';
+    const result = terminalResult(chain.state);
+    parts.push(`- [${result}] ${task} (scores: ${scores})`);
+  }
+
+  parts.push('');
+  parts.push('--- END OLDER AGENTS ---');
+  parts.push('');
+  parts.push('Provide aggregate summary now:');
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Resolved problems prompt (LLM-assisted)
+// ---------------------------------------------------------------------------
+
+/**
+ * buildResolvedProblemsPrompt — build the prompt for LLM-assisted extraction
+ * of problem → resolution pairs from the conversation.
+ *
+ * Returns empty string if no messages.
+ */
+export function buildResolvedProblemsPrompt(
+  messages: ProviderMessage[],
+): string {
+  if (messages.length === 0) return '';
+
+  const parts: string[] = [
+    'Extract problem → resolution pairs from this conversation.',
+    'Only include problems that were actually resolved. One line each.',
+    'Format: problem → resolution.',
+    'Highlight the resolution, not the debugging journey.',
+    '',
+    '--- CONVERSATION ---',
+    '',
+  ];
+
+  for (const msg of messages) {
+    const text = extractText(msg.content);
+    if (text.trim()) {
+      parts.push(`[${msg.role}]: ${text.trim().slice(0, 1000)}`);
+      parts.push('');
+    }
+  }
+
+  parts.push('--- END CONVERSATION ---');
+  parts.push('');
+  parts.push('List resolved problems now (or return empty if none):');
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Plan progress
+// ---------------------------------------------------------------------------
+
+/**
+ * buildPlanProgress — rule-based from plan state.
+ * Returns null if no active plan.
+ */
+export function buildPlanProgress(
+  plan: ExecutionPlan | null,
+): CompactionSection | null {
+  if (!plan) return null;
+
+  const lines: string[] = [];
+
+  // Group items by phase
+  const byPhase = new Map<string, PlanItem[]>();
+  const phaseOrder: string[] = [];
+  for (const item of plan.items) {
+    if (!byPhase.has(item.phase)) {
+      byPhase.set(item.phase, []);
+      phaseOrder.push(item.phase);
+    }
+    byPhase.get(item.phase)!.push(item);
+  }
+
+  for (const phase of phaseOrder) {
+    const items = byPhase.get(phase)!;
+    const done = items.filter(
+      (i) => i.status === 'complete' || i.status === 'skipped',
+    ).length;
+    const inProgress = items.some((i) => i.status === 'in_progress');
+    const failed = items.some((i) => i.status === 'failed');
+    const all = items.length;
+    const allDone = done === all;
+
+    let status: string;
+    if (allDone) status = 'COMPLETE';
+    else if (failed) status = `FAILED (${done}/${all} done)`;
+    else if (inProgress) status = `IN_PROGRESS (${done}/${all} done)`;
+    else status = `PENDING (${done}/${all} done)`;
+
+    lines.push(`- ${phase}: [${status}]`);
+  }
+
+  if (lines.length === 0) return null;
+
+  const content = `**${plan.title}**\n${lines.join('\n')}`;
+  return makeSection('plan-progress', '## Plan Progress', content);
+}
+
+// ---------------------------------------------------------------------------
+// Session lineage
+// ---------------------------------------------------------------------------
+
+/**
+ * buildSessionLineage — format the append-only micro-log.
+ * Each compaction adds one entry; prior entries are never modified.
+ */
+export function buildSessionLineage(
+  originalTask: string | undefined,
+  lineageEntries: string[],
+  compactionCount: number,
+): CompactionSection | null {
+  const lines: string[] = [];
+
+  if (originalTask) {
+    lines.push(`Original task: "${originalTask}"`);
+  }
+  lines.push(`Compactions: ${compactionCount}`);
+  for (const entry of lineageEntries) {
+    lines.push(entry);
+  }
+
+  if (lines.length === 0) return null;
+  return makeSection('session-lineage', '## Session Lineage', lines.join('\n'));
+}

package/src/core/compaction-types.ts

@@ -0,0 +1,147 @@
+/**
+ * compaction-types.ts
+ *
+ * Shared types for the prompt compaction engine.
+ */
+
+import type { ProviderMessage } from '../providers/interface.ts';
+import type { SessionMemory } from '@pellux/goodvibes-sdk/platform/core/session-memory';
+import type { AgentRecord } from '../tools/agent/index.ts';
+import type { WrfcChain } from '../agents/wrfc-types.ts';
+import type { ExecutionPlan } from '@pellux/goodvibes-sdk/platform/core/execution-plan';
+
+// ---------------------------------------------------------------------------
+// Section types
+// ---------------------------------------------------------------------------
+
+/** A single compacted output section. */
+export interface CompactionSection {
+  /** Unique identifier for this section (e.g. 'handoff-header', 'current-task'). */
+  id: string;
+  /** Section heading text (e.g. '## Current Task'). Empty string for the handoff header. */
+  header: string;
+  /** Body content for this section. */
+  content: string;
+  /** Estimated token count for this section. */
+  tokens: number;
+}
+
+/** Per-section token budgets and threshold configuration. */
+export interface CompactionConfig {
+  /** Max tokens for recent conversation gather (default: 3000). */
+  recentConversationBudget: number;
+  /** Max tokens for tool results section (default: 1500). */
+  toolResultsBudget: number;
+  /** Max tokens for agent activity table (default: 1500). */
+  agentActivityBudget: number;
+  /** Max tokens for older agent summary (default: 500). */
+  olderAgentSummaryBudget: number;
+  /** Max tokens for resolved problems section (default: 300). */
+  resolvedProblemsBudget: number;
+  /** Overall ceiling for entire compacted output (default: 6500). */
+  totalCeiling: number;
+}
+
+/** Default compaction configuration. */
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+  recentConversationBudget: 3000,
+  toolResultsBudget: 1500,
+  agentActivityBudget: 1500,
+  olderAgentSummaryBudget: 500,
+  resolvedProblemsBudget: 300,
+  totalCeiling: 6500,
+};
+
+// ---------------------------------------------------------------------------
+// Session memory (re-exported for consumers of this module)
+// ---------------------------------------------------------------------------
+
+export type { SessionMemory };
+
+// ---------------------------------------------------------------------------
+// Token estimation utility (here to avoid circular imports)
+// ---------------------------------------------------------------------------
+
+/** Rough token estimate for a string: 4 chars ≈ 1 token. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Context data sources (read-only, passed in as plain data — no singletons)
+// ---------------------------------------------------------------------------
+
+/** All data sources needed for compaction. Accept as plain data; do not import singletons. */
+export interface CompactionContext {
+  /** Current conversation messages (as sent to LLM — no system messages). */
+  messages: ProviderMessage[];
+
+  /** Pinned session memories (survive all compactions). */
+  sessionMemories: readonly SessionMemory[];
+
+  /** All agent records from AgentManager.list(). */
+  agents: AgentRecord[];
+
+  /** All WRFC chains from WrfcController.listChains(). */
+  wrfcChains: WrfcChain[];
+
+  /** Active execution plan, or null if none. */
+  activePlan: ExecutionPlan | null;
+
+  /** Append-only session lineage log entries (one per prior compaction). */
+  lineageEntries: string[];
+
+  /** Original task description for lineage. Set on first compaction. */
+  originalTask?: string;
+
+  /** Number of compactions performed so far (including this one). */
+  compactionCount: number;
+
+  /** Context window size for the current model (used for threshold scaling). */
+  contextWindow: number;
+
+  /** Whether this compaction was triggered automatically or manually. */
+  trigger: 'auto' | 'manual';
+
+  /** Model ID used for LLM extraction calls. */
+  extractionModelId: string;
+
+  /** Optional provider name for extraction model disambiguation. */
+  extractionProvider?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Compaction events and results
+// ---------------------------------------------------------------------------
+
+/** Record of a completed compaction event. */
+export interface CompactionEvent {
+  timestamp: number;
+  messagesBeforeCompaction: number;
+  messagesAfterCompaction: number;
+  tokensBeforeEstimate: number;
+  tokensAfterEstimate: number;
+  modelId: string;
+  trigger: 'auto' | 'manual';
+  /** Sections included in this compaction (IDs). */
+  sectionsIncluded?: string[];
+  /** Whether post-compaction validation passed. */
+  validationPassed?: boolean;
+}
+
+/** Result of a compaction operation. */
+export interface CompactionResult {
+  /** The new compacted message list (single user message containing the handoff). */
+  messages: ProviderMessage[];
+  /** The full compacted context text. */
+  summary: string;
+  /** Token estimates before and after compaction. */
+  tokensBeforeEstimate: number;
+  tokensAfterEstimate: number;
+  /** The compaction event record for tracking. */
+  event: CompactionEvent;
+  /** Sections that were included (for debugging). */
+  sections: CompactionSection[];
+  /** Post-compaction validation warnings (empty = all checks passed). */
+  validationWarnings: string[];
+}

package/src/core/composer-state.ts

@@ -0,0 +1,59 @@
+import type { SubmissionIntent } from '../input/submission-intent.ts';
+import { routeSubmissionIntent, type SubmissionRouterInput } from '../input/submission-router.ts';
+import type { TurnState } from '../runtime/store/domains/conversation.ts';
+
+export interface ComposerState {
+  readonly intent: SubmissionIntent;
+  readonly modeLabel: string;
+  readonly statusLabel: string;
+  readonly pendingRisk: 'none' | 'approval-wait' | 'shell' | 'command' | 'remote';
+  readonly flags: readonly string[];
+}
+
+export interface ComposerStateInput extends SubmissionRouterInput {
+  readonly pendingApproval?: boolean;
+  readonly turnState?: TurnState;
+}
+
+export function deriveComposerState(input: ComposerStateInput): ComposerState {
+  const intent = routeSubmissionIntent(input);
+  const flags: string[] = [];
+  let pendingRisk: ComposerState['pendingRisk'] = 'none';
+
+  if (input.pendingApproval) {
+    flags.push('approval');
+    pendingRisk = 'approval-wait';
+  }
+  if (intent.kind === 'shell') {
+    flags.push('shell');
+    if (pendingRisk === 'none') pendingRisk = 'shell';
+  } else if (intent.kind === 'slash-command' || intent.kind === 'plan' || intent.kind === 'review') {
+    if (pendingRisk === 'none') pendingRisk = 'command';
+  } else if (intent.kind === 'orchestration') {
+    flags.push('orchestration');
+    if (pendingRisk === 'none') pendingRisk = 'remote';
+  }
+  if (input.hasAttachments) flags.push('attachments');
+
+  const statusLabel = (() => {
+    switch (input.turnState) {
+      case 'preflight': return 'preflight';
+      case 'streaming': return 'streaming';
+      case 'tool_dispatch': return 'tools';
+      case 'post_hooks': return 'post-hooks';
+      case 'failed': return 'failed';
+      case 'cancelled': return 'cancelled';
+      case 'completed': return 'completed';
+      default: return 'idle';
+    }
+  })();
+
+  return {
+    intent,
+    modeLabel: intent.label,
+    statusLabel,
+    pendingRisk,
+    flags,
+  };
+}
+