@pellux/goodvibes-tui 1.20.0 → 1.21.0

package/src/core/conversation.ts

@@ -5,8 +5,7 @@ import type { ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types'
 import type { ProviderMessage, ContentPart } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { TranscriptEventKind } from '@pellux/goodvibes-sdk/platform/core';
-// SystemMessageKind imported from runtime directly to avoid cycle:
-//   conversation.ts → system-message-router.ts → conversation.ts
+// SystemMessageKind imported from runtime directly to avoid cycle: conversation.ts → system-message-router.ts → conversation.ts
 import type { SystemMessageKind } from '@/runtime/index.ts';
 import {
   ConversationManager as SdkConversationManager,
@@ -14,6 +13,10 @@ import {
 } from '@pellux/goodvibes-sdk/platform/core';
 import type { BlockMeta } from './conversation-types.ts';
 import { MessageLineCache } from './conversation-line-cache.ts';
+import { UserReceiptIndices } from './conversation-user-receipts.ts';
+import { SplashGateState } from './conversation-splash-state.ts';
+import { resolveTranscriptEventLine } from './conversation-event-navigation.ts';
+import { SearchExpansionTracker } from './conversation-search-expansion.ts';
 import {
   addConversationSplashScreen,
   conversationTextToLines,
@@ -110,6 +113,7 @@ export class ConversationManager extends SdkConversationManager {
   private _configManager: ConfigManager | null = null;
   /** Collapse state: stable key (msg_N) -> collapsed (true = collapsed). */
   private collapseState: Map<string, boolean> = new Map();
+  public readonly searchExpansion = new SearchExpansionTracker();
   /** Block registry: track rendered blocks for copy/apply. */
   protected blockRegistry: BlockMeta[] = [];
   /**
@@ -139,6 +143,8 @@ export class ConversationManager extends SdkConversationManager {
   private errorLineRegistry: number[] = [];
   /** Maps message index → SystemMessageKind for system-role messages. */
   private messageKindRegistry: Map<number, SystemMessageKind> = new Map();
+  /** See conversation-user-receipts.ts. */
+  private userReceiptIndices = new UserReceiptIndices();
   /** Streaming block start line in history buffer (for incremental streaming update). */
   private streamingStartLine = -1;
   /**
@@ -164,6 +170,8 @@ export class ConversationManager extends SdkConversationManager {
 
   public suppressSplash: boolean = false;
   public splashOptions: SplashOptions = {};
+  /** Run-sticky dismissal + the splash→transcript edge (conversation-splash-state.ts). */
+  private readonly splashGate = new SplashGateState();
 
   constructor(
     getWidth: () => number = () => process.stdout.columns || 80,
@@ -221,25 +229,21 @@ export class ConversationManager extends SdkConversationManager {
     // stale kind (e.g. 'operational') and silently mis-classify the new message.
     const nextIndex = this.getMessageSnapshot().length;
     this.messageKindRegistry.delete(nextIndex);
+    this.userReceiptIndices.delete(nextIndex);
     super.addSystemMessage(content);
     this.markDirty();
   }
 
   /**
-   * addTypedSystemMessage - Add a system message with an explicit kind tag.
-   * The kind is stored in messageKindRegistry (keyed by the message index that
-   * will be assigned after the push) so that renderConversationSystemMessage
-   * can use it instead of text-based pattern matching.
-   *
-   * Called by SystemMessageRouter.routeTypedSystemMessage when routing to the
-   * conversation surface. Falls back to addSystemMessage for callers that do
-   * not have kind information.
+   * addTypedSystemMessage - System message with an explicit kind tag, stored
+   * in messageKindRegistry. `isUserReceipt` (conversation-user-receipts.ts)
+   * additionally marks it for rebuildHistory()'s splash check — only for a
+   * direct receipt to an explicit user action, never ambient boot chatter.
    */
-  public addTypedSystemMessage(content: string, kind: SystemMessageKind): void {
-    // getMessageSnapshot().length is the index this message will receive after
-    // addSystemMessage appends it to the messages array.
+  public addTypedSystemMessage(content: string, kind: SystemMessageKind, opts?: { isUserReceipt?: boolean }): void {
     const nextIndex = this.getMessageSnapshot().length;
     this.messageKindRegistry.set(nextIndex, kind);
+    if (opts?.isUserReceipt) this.userReceiptIndices.add(nextIndex); else this.userReceiptIndices.delete(nextIndex);
     super.addSystemMessage(content);
     this.markDirty();
   }
@@ -256,6 +260,7 @@ export class ConversationManager extends SdkConversationManager {
       for (const key of this.messageKindRegistry.keys()) {
         if (key >= postUndoCount) this.messageKindRegistry.delete(key);
       }
+      this.userReceiptIndices.purgeFrom(postUndoCount);
       this.markDirty();
     }
     return result;
@@ -357,6 +362,7 @@ export class ConversationManager extends SdkConversationManager {
     this.messageLineRegistry = [];
     this.errorLineRegistry = [];
     this.messageKindRegistry = new Map();
+    this.userReceiptIndices.clear();
     this.streamingStartLine = -1;
     this._displayFromMessageIndex = 0; // full reset — show everything on next render
   }
@@ -478,17 +484,21 @@ export class ConversationManager extends SdkConversationManager {
     const displayStart = this._displayFromMessageIndex;
     const visibleSnapshot = displayStart > 0 ? renderSnapshot.slice(displayStart) : renderSnapshot;
 
-    // Tool messages ARE rendered (as collapsed blocks); this filter is only
-    // for determining whether to show the splash screen (tool-only messages
-    // don't count as visible conversation content for splash purposes).
-    const displayMessages = visibleSnapshot.filter(
-      (m) => m.role !== 'tool' && m.role !== 'system',
-    );
+    // Tool/system messages aren't visible splash-purposes content, except a
+    // system message in userReceiptIndices. visibleSnapshot mirrors the
+    // snapshot 1:1 (only front-sliced), so index i is absolute displayStart+i.
+    const displayMessages = visibleSnapshot.filter((m, i) => {
+      if (m.role === 'tool') return false;
+      if (m.role === 'system') return this.userReceiptIndices.has(displayStart + i);
+      return true;
+    });
 
-    if (displayMessages.length === 0 && displayStart === 0 && !this.suppressSplash) {
+    if (displayMessages.length === 0 && displayStart === 0 && !this.suppressSplash && !this.splashGate.dismissed) {
       this.addSplashScreen(width);
+      this.splashGate.enter();
       return;
     }
+    this.splashGate.leave(); // latches the splash→transcript edge for consumeSplashTransition()
 
     // The in-progress streaming placeholder (rendered EMPTY above via
     // renderSnapshot) is left uncached: its content mutates in place per delta and
@@ -640,6 +650,7 @@ export class ConversationManager extends SdkConversationManager {
     if (!nearest) return -1;
     const current = this.collapseState.get(nearest.collapseKey) ?? false;
     this.collapseState.set(nearest.collapseKey, !current);
+    this.searchExpansion.noteUserTouch(nearest.collapseKey);
     this.markDirty();
     return nearest.blockIndex;
   }
@@ -701,30 +712,12 @@ export class ConversationManager extends SdkConversationManager {
 
   public nextTranscriptEventLine(currentLine: number, kind: TranscriptEventKind | 'all' = 'all'): number {
     this.flushHistory();
-    const index = this.getTranscriptEventIndex();
-    const events = kind === 'all' ? index.events : index.events.filter((event) => event.kind === kind);
-    if (events.length === 0) return -1;
-    const lines = events
-      .map((event) => this.messageLineRegistry[event.messageIndex] ?? -1)
-      .filter((line) => line >= 0)
-      .sort((a, b) => a - b);
-    if (lines.length === 0) return -1;
-    const after = lines.find((line) => line > currentLine);
-    return after ?? lines[0]!;
+    return resolveTranscriptEventLine(this.getTranscriptEventIndex().events, kind, this.messageLineRegistry, currentLine, 'next');
   }
 
   public prevTranscriptEventLine(currentLine: number, kind: TranscriptEventKind | 'all' = 'all'): number {
     this.flushHistory();
-    const index = this.getTranscriptEventIndex();
-    const events = kind === 'all' ? index.events : index.events.filter((event) => event.kind === kind);
-    if (events.length === 0) return -1;
-    const lines = events
-      .map((event) => this.messageLineRegistry[event.messageIndex] ?? -1)
-      .filter((line) => line >= 0)
-      .sort((a, b) => a - b);
-    if (lines.length === 0) return -1;
-    const before = [...lines].reverse().find((line) => line < currentLine);
-    return before ?? lines[lines.length - 1]!;
+    return resolveTranscriptEventLine(this.getTranscriptEventIndex().events, kind, this.messageLineRegistry, currentLine, 'prev');
   }
 
   public setSplashSuppressed(suppressed: boolean): void {
@@ -733,6 +726,16 @@ export class ConversationManager extends SdkConversationManager {
     this.markDirty();
   }
 
+  /** Retire the splash for the run — any submission does it (SplashGateState). */
+  public dismissSplash(): void {
+    if (this.splashGate.dismiss()) this.markDirty();
+  }
+
+  /** True once, on the frame the splash gives way to transcript content. */
+  public consumeSplashTransition(): boolean {
+    return this.splashGate.consumeTransition();
+  }
+
   private addSplashScreen(width: number): void {
     addConversationSplashScreen(this.renderingContext(), width);
   }

package/src/core/model-routing-chip.ts

@@ -9,18 +9,22 @@
  * narration of their own.
  *
  * Division of labour with the failover path: the optimizer-gated failover in
- * stream-event-wiring.ts already renders a richer `[Failover] from → to
- * (reason)(+cost)` line AND records the transition into the optimizer's
- * fallback log. So when a MODEL_CHANGED correlates to a just-recorded fallback
- * transition, this chip stays silent (buildRoutingChip returns null) — the
- * [Failover] line already narrated that exact change with its real reason.
- * Every other change is surfaced here.
+ * stream-event-wiring.ts renders a richer `[Failover] from → to
+ * (reason)(+cost)` line for the switches it makes itself, and tells this
+ * listener so directly (see the self-narrated guard there) rather than relying
+ * on this module to infer it. Those changes never reach buildRoutingChip.
  *
- * Reason honesty: for the paths this chip surfaces the routing layer exposes no
- * machine-readable reason (a deliberate user switch has none; an SDK-internal
- * downgrade does not thread one to the TUI), so the notice states "reason
- * unknown" rather than omitting the change — per the honesty rule that a change
- * with no explanation is still reported, just marked unknown.
+ * Reason honesty, in three tiers:
+ *   1. a change the failover path already narrated → not offered here at all;
+ *   2. a change that correlates to a transition in the optimizer's fallback
+ *      log → the log's own reason is quoted, because the reason IS known. The
+ *      log is shared: the TUI's failover records provider ids ("abacusai"),
+ *      the SDK's agent-orchestrator fallback records registry keys
+ *      ("abacusai:route-llm"), and a match on either form counts. Reading only
+ *      one form is what made a real, explained failover print
+ *      "(reason unknown)";
+ *   3. no correlation → "(reason unknown)", because a change with no
+ *      explanation is still reported, just honestly marked as unexplained.
  */
 
 /** The subset of a FallbackTransition this module reads (structural, SDK-agnostic). */
@@ -44,9 +48,22 @@ export const FALLBACK_CORRELATION_WINDOW_MS = 4_000;
 /** The forced conversation prefix so the notice is never gated as noise or routed away. */
 export const ROUTING_CHIP_PREFIX = '[Routing]';
 
+/**
+ * The provider id of a fallback-log endpoint, which may be written either as a
+ * bare provider id or as a `provider:model` registry key depending on which
+ * writer recorded it. Everything before the first ':' is the provider in both
+ * forms, so one rule reads both.
+ */
+function providerOf(endpoint: string): string {
+  const separator = endpoint.indexOf(':');
+  return separator === -1 ? endpoint : endpoint.slice(0, separator);
+}
+
 /**
  * Most recent fallback-log reason for a from→to provider transition within the
  * correlation window, or null. Scans newest-first so the freshest transition wins.
+ * Endpoints are compared by provider id, so entries recorded as registry keys
+ * correlate exactly like entries recorded as bare provider ids.
  */
 export function findRecentFallbackReason(
   fallbackLog: readonly FallbackTransitionLike[],
@@ -57,17 +74,20 @@ export function findRecentFallbackReason(
 ): string | null {
   for (let i = fallbackLog.length - 1; i >= 0; i--) {
     const t = fallbackLog[i]!;
-    if (t.from === fromProvider && t.to === toProvider && now - t.ts <= windowMs) return t.reason;
+    if (providerOf(t.from) === providerOf(fromProvider)
+      && providerOf(t.to) === providerOf(toProvider)
+      && now - t.ts <= windowMs) return t.reason;
   }
   return null;
 }
 
 /**
  * The routing-chip line to emit for a MODEL_CHANGED event, or null to stay
- * silent. Null only when there is no real change (no/same previous model) or
- * when the change was a failover already narrated by its own [Failover] line
- * (correlated via the fallback log). Otherwise returns the honest
- * `[Routing] model changed: old → new (reason unknown)` notice.
+ * silent. Null only when there is no real change (no/same previous model) —
+ * changes the failover path narrates itself never reach this function.
+ *
+ * A change that correlates to a logged fallback transition is reported WITH
+ * that transition's reason; anything else is reported as "reason unknown".
  */
 export function buildRoutingChip(
   change: ModelChangedLike,
@@ -77,6 +97,6 @@ export function buildRoutingChip(
   const prev = change.previous;
   if (!prev || prev.registryKey === change.registryKey) return null;
   const failoverReason = findRecentFallbackReason(fallbackLog, prev.provider, change.provider, now);
-  if (failoverReason !== null) return null; // [Failover] already narrated this transition
-  return `${ROUTING_CHIP_PREFIX} model changed: ${prev.registryKey} → ${change.registryKey} (reason unknown)`;
+  const reason = failoverReason === null ? 'reason unknown' : `failover: ${failoverReason}`;
+  return `${ROUTING_CHIP_PREFIX} model changed: ${prev.registryKey} → ${change.registryKey} (${reason})`;
 }

package/src/core/rewind-turn-anchors.ts

@@ -21,7 +21,7 @@
  * `messageCount` boundaries stay valid because a resume rehydrates the same
  * message history the anchors were recorded against.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { SessionSurface } from '@/runtime/index.ts';
 
@@ -92,12 +92,14 @@ export function clearTurnAnchors(sessionId: string): void {
 const ANCHOR_SIDECAR_VERSION = 1;
 
 /** Absolute path to a session's anchor sidecar, or null when inputs are unusable. */
+const ANCHOR_SIDECAR_SUFFIX = '.anchors.json';
+
 function anchorSidecarPath(sessionId: string, surface: SessionSurface): string | null {
   if (!sessionId || !surface.sessionsDir) return null;
   // A sessionId is a filename component; refuse anything with path separators so
   // a malformed id can never escape the sessions directory.
   if (/[\\/]/.test(sessionId)) return null;
-  return join(surface.sessionsDir, `${sessionId}.anchors.json`);
+  return join(surface.sessionsDir, `${sessionId}${ANCHOR_SIDECAR_SUFFIX}`);
 }
 
 function isTurnAnchor(value: unknown): value is TurnAnchor {
@@ -125,7 +127,7 @@ export function persistTurnAnchors(sessionId: string, surface: SessionSurface):
   try {
     mkdirSync(surface.sessionsDir, { recursive: true });
     const payload = JSON.stringify({ version: ANCHOR_SIDECAR_VERSION, sessionId, anchors: list });
-    const tmp = `${path}.tmp-${process.pid}`;
+    const tmp = `${path}${ANCHOR_SIDECAR_TMP_MARKER}${process.pid}`;
     writeFileSync(tmp, payload);
     renameSync(tmp, path);
   } catch {
@@ -157,3 +159,153 @@ export function restoreTurnAnchors(sessionId: string, surface: SessionSurface):
     return 0;
   }
 }
+
+// ─── Reaping orphaned sidecars ────────────────────────────────────────────────
+//
+// A sidecar's OWNER is the session JSONL it sits beside. Deleting a session
+// removes the JSONL but nothing ever removed the sidecar, so anchors for
+// sessions that no longer exist accumulate in the sessions directory forever.
+// The sweep below reclaims them, plus the `.tmp-<pid>` staging files a crash
+// between write and rename leaves behind.
+
+/** Infix for the atomic-write staging file, before the writing process's pid. */
+const ANCHOR_SIDECAR_TMP_MARKER = '.tmp-';
+
+/**
+ * How long a staging file is tolerated before it is treated as crash residue:
+ * 1 hour. `persistTurnAnchors` renames within microseconds of writing, so
+ * anything this old was interrupted, and the completed sidecar (if the write
+ * ever finished) is a separate file.
+ */
+export const ANCHOR_TMP_MAX_AGE_MS = 60 * 60 * 1000;
+
+/**
+ * How settled a sidecar must be before this sweep will delete it: 1 hour.
+ *
+ * Another instance can be persisting anchors for a session this process knows
+ * nothing about, and the window between reading a sidecar's content and
+ * unlinking it is not atomic. Requiring the file to have been untouched for an
+ * hour means a sidecar that some other instance is actively rewriting is never
+ * a candidate, while genuine residue — whose writer is long gone — always is.
+ * The sweep repeats, so the delay costs nothing.
+ */
+export const ANCHOR_SIDECAR_SETTLE_MS = 60 * 60 * 1000;
+
+export interface AnchorSidecarReapResult {
+  /** Sidecar and staging files examined this sweep. */
+  readonly scanned: number;
+  /** Files deleted this sweep. */
+  readonly reaped: number;
+}
+
+export interface AnchorSidecarReapOptions {
+  /** The session this process is using right now; its sidecar is never reaped. */
+  readonly currentSessionId?: string | null;
+  readonly now?: () => number;
+  /** Override the staging-file age window (tests). */
+  readonly tmpMaxAgeMs?: number;
+  /** Override how long a sidecar must be untouched before it can be reaped (tests). */
+  readonly settleMs?: number;
+}
+
+/**
+ * Delete anchor sidecars whose owning session file is gone, sidecars that hold
+ * nothing readable, and abandoned staging files.
+ *
+ * A sidecar survives when `<sessionsDir>/<sessionId>.jsonl` still exists AND
+ * the sidecar itself parses into at least one usable anchor — content, not
+ * mere existence, because a sidecar truncated by a crash restores nothing and
+ * would otherwise sit there indefinitely looking like valid state. It also
+ * survives while it is still fresh (see `ANCHOR_SIDECAR_SETTLE_MS`), which
+ * keeps a sidecar another instance is mid-rewrite out of reach.
+ *
+ * The current session's sidecar is never touched, and an unreadable or absent
+ * sessions directory simply reclaims nothing. Idempotent and concurrency-safe:
+ * a file another sweeper unlinked first (ENOENT) counts as reaped.
+ */
+export function reapOrphanedAnchorSidecars(
+  surface: SessionSurface,
+  options: AnchorSidecarReapOptions = {},
+): AnchorSidecarReapResult {
+  const dir = surface.sessionsDir;
+  if (!dir) return { scanned: 0, reaped: 0 };
+
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter(
+      (n) => n.endsWith(ANCHOR_SIDECAR_SUFFIX) || n.includes(`${ANCHOR_SIDECAR_SUFFIX}${ANCHOR_SIDECAR_TMP_MARKER}`),
+    );
+  } catch {
+    return { scanned: 0, reaped: 0 };
+  }
+
+  const now = options.now?.() ?? Date.now();
+  const tmpMaxAgeMs = options.tmpMaxAgeMs ?? ANCHOR_TMP_MAX_AGE_MS;
+  const settleMs = options.settleMs ?? ANCHOR_SIDECAR_SETTLE_MS;
+  let reaped = 0;
+
+  for (const name of names) {
+    const path = join(dir, name);
+
+    if (!name.endsWith(ANCHOR_SIDECAR_SUFFIX)) {
+      // A `<sessionId>.anchors.json.tmp-<pid>` staging file. Age alone decides:
+      // a young one may belong to another instance's in-flight write.
+      let mtimeMs: number;
+      try {
+        mtimeMs = statSync(path).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (now - mtimeMs > tmpMaxAgeMs && unlinkAnchorFile(path)) reaped++;
+      continue;
+    }
+
+    const sessionId = name.slice(0, name.length - ANCHOR_SIDECAR_SUFFIX.length);
+    if (sessionId.length === 0) continue;
+    if (options.currentSessionId && sessionId === options.currentSessionId) continue;
+
+    // A sidecar written moments ago belongs to a writer that is still around —
+    // possibly another instance whose session this process cannot see.
+    let sidecarMtimeMs: number;
+    try {
+      sidecarMtimeMs = statSync(path).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - sidecarMtimeMs <= settleMs) continue;
+
+    if (!existsSync(join(dir, `${sessionId}.jsonl`))) {
+      // The owning session is gone — this sidecar can never be used again.
+      if (unlinkAnchorFile(path)) reaped++;
+      continue;
+    }
+    if (!sidecarHoldsAnchors(path)) {
+      // The session survives but the sidecar is empty or torn: it restores
+      // nothing, so keeping it only hides the loss.
+      if (unlinkAnchorFile(path)) reaped++;
+    }
+  }
+
+  return { scanned: names.length, reaped };
+}
+
+/** Content check: does this sidecar parse into at least one usable anchor? */
+function sidecarHoldsAnchors(path: string): boolean {
+  try {
+    const text = readFileSync(path, 'utf8');
+    if (text.trim().length === 0) return false;
+    const parsed = JSON.parse(text) as { anchors?: unknown };
+    return Array.isArray(parsed?.anchors) && parsed.anchors.some(isTurnAnchor);
+  } catch {
+    return false;
+  }
+}
+
+function unlinkAnchorFile(path: string): boolean {
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
+  }
+}