@pellux/goodvibes-tui 0.22.0 → 0.24.0

package/src/core/long-task-notifier.ts

@@ -0,0 +1,145 @@
+/**
+ * long-task-notifier — fires push notifications when a turn or agent task
+ * completes after running longer than the configured threshold.
+ *
+ * PRIVACY GUARANTEE: Notification text must never include conversation content
+ * (user messages, assistant replies, tool outputs). Only metadata is included:
+ * task kind, elapsed time, ok/fail status, and session id. This module enforces
+ * that constraint by construction — it receives no conversation object and
+ * builds all message text from structural metadata only.
+ *
+ * Delivery targets (in preference order):
+ *   1. Desktop notification (linux notify-send / mac osascript) via SDK
+ *      notifyCompletion — detected and dispatched by the SDK; silently
+ *      no-ops when the platform does not support it.
+ *   2. Configured outbound webhook channel (ntfy topic / webhook URL) via
+ *      WebhookNotifier.send() — only fires when the user has URLs configured.
+ *
+ * When neither target is available the function is an honest no-op (debug log
+ * only; no user-facing error spam).
+ *
+ * Focus tracking: terminal focus state is not tracked anywhere in the TUI.
+ * Notifications therefore fire regardless of whether the terminal window is
+ * focused. A future implementation may suppress notifications when the TUI is
+ * in the foreground by reading a focus-state ref. // seam: wire focus ref here.
+ */
+
+import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+
+/** Default threshold in seconds. Turns shorter than this do not notify. */
+export const NOTIFY_AFTER_SECONDS_DEFAULT = 60;
+
+/**
+ * Sentinel value for the off-state. When behavior.notifyAfterSeconds is 0,
+ * push notifications are disabled (same convention as other numeric-off keys
+ * in the config schema).
+ */
+export const NOTIFY_AFTER_SECONDS_OFF = 0;
+
+/** Accepted task kinds for notification messages. */
+export type LongTaskKind = 'turn' | 'agent';
+
+/** Completion status for notification messages. */
+export type LongTaskStatus = 'ok' | 'fail';
+
+export interface MaybeNotifyLongTaskOptions {
+  /**
+   * Elapsed milliseconds for the turn or agent task.
+   * Must not include any conversation content.
+   */
+  readonly elapsedMs: number;
+
+  /** Whether the task completed successfully or failed. */
+  readonly status: LongTaskStatus;
+
+  /** Task kind label for the notification body. */
+  readonly kind: LongTaskKind;
+
+  /** Session id for correlation. Must not be a PII value. */
+  readonly sessionId: string;
+
+  /**
+   * Threshold in seconds from config (behavior.notifyAfterSeconds).
+   * 0 means off; notifications are suppressed entirely.
+   * Should be the raw config value; this function normalises it.
+   */
+  readonly thresholdSeconds: number;
+
+  /**
+   * Outbound webhook notifier. When provided and the user has URLs
+   * configured, the notification is also sent to all configured endpoints
+   * (e.g. ntfy.sh topics). Optional — absent means outbound delivery is
+   * skipped silently.
+   */
+  readonly webhookNotifier?: WebhookNotifier | null;
+}
+
+/**
+ * Fires push notifications for a completed long task if the elapsed time
+ * exceeds the configured threshold.
+ *
+ * Returns true when at least one delivery was attempted, false when the
+ * call was a no-op (threshold not reached, or off-state).
+ *
+ * PRIVACY: builds message text from structural metadata only (kind, elapsed,
+ * status, sessionId). Never includes conversation content.
+ */
+export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
+  const { elapsedMs, status, kind, sessionId, thresholdSeconds, webhookNotifier } = opts;
+
+  // Off-state: 0 disables notifications entirely.
+  if (thresholdSeconds === NOTIFY_AFTER_SECONDS_OFF) {
+    logger.debug('long-task-notifier: disabled (threshold=0)');
+    return false;
+  }
+
+  // Gate: only notify when the task exceeded the threshold.
+  const elapsedSeconds = Math.floor(elapsedMs / 1000);
+  if (elapsedSeconds < thresholdSeconds) {
+    logger.debug('long-task-notifier: below threshold', { elapsedSeconds, thresholdSeconds });
+    return false;
+  }
+
+  // Build concise, metadata-only message. No conversation text.
+  const statusLabel = status === 'ok' ? 'completed' : 'failed';
+  const title = `GoodVibes — ${kind} ${statusLabel}`;
+  // PRIVACY: message contains only structural metadata, never conversation content.
+  const message = `${kind} ${statusLabel} in ${elapsedSeconds}s  ·  session ${sessionId.slice(0, 8)}`;
+
+  // Delivery 1: desktop notification (notify-send on linux, osascript on mac).
+  // notifyCompletion is non-throwing; SDK handles platform absence silently.
+  try {
+    notifyCompletion(title, message, elapsedMs);
+  } catch (err) {
+    logger.debug('long-task-notifier: desktop notify error', { error: String(err) });
+  }
+
+  // Delivery 2: outbound webhook (ntfy / generic endpoint) if configured.
+  if (webhookNotifier) {
+    const urls = webhookNotifier.getUrls();
+    if (urls.length > 0) {
+      webhookNotifier.send(message).catch((err: unknown) => {
+        logger.debug('long-task-notifier: webhook send error', { error: String(err) });
+      });
+    } else {
+      logger.debug('long-task-notifier: no webhook URLs configured, skipping outbound delivery');
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Read behavior.notifyAfterSeconds from a config manager.
+ * Returns NOTIFY_AFTER_SECONDS_DEFAULT when the key is absent or invalid.
+ * Returns NOTIFY_AFTER_SECONDS_OFF (0) when explicitly set to 0.
+ */
+export function readNotifyAfterSeconds(configGet: (key: string) => unknown): number {
+  const raw = configGet('behavior.notifyAfterSeconds');
+  if (raw === 0) return NOTIFY_AFTER_SECONDS_OFF;
+  const parsed = typeof raw === 'number' ? raw : Number(raw);
+  if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  return NOTIFY_AFTER_SECONDS_DEFAULT;
+}

package/src/core/session-recovery.ts

@@ -0,0 +1,147 @@
+/**
+ * session-recovery.ts — Journal replay at session resume.
+ *
+ * Purpose
+ * ───────
+ * When a session is resumed, this module checks whether a transcript journal
+ * exists for that session whose records post-date the loaded snapshot. If so,
+ * it replays those records onto the live conversation and writes a fresh
+ * snapshot so the gap is permanently closed.
+ *
+ * Seams (all three must call replayJournalForSession)
+ * ────────────────────────────────────────────────────
+ * 1. CLI / command resume — session-workflow.ts, after `fromJSON` +
+ *    `rebuildHistory` complete. Handles --continue, --resume, /session resume,
+ *    and --fork.
+ * 2. Ctrl+R crash recovery — blocking-input.ts, after `conversation.fromJSON`
+ *    in the Ctrl+R branch. Handles SIGKILL-era recovery files.
+ * 3. In-TUI panel resume — bootstrap-hook-bridge.ts
+ *    `createResumeSessionHandler`, after `options.runtime.sessionId` is
+ *    assigned. Handles the session browser / panel-driven resume.
+ *
+ * Recovery protocol
+ * ─────────────────
+ * 1. Call replayJournal() with the journal path and the snapshot timestamp.
+ * 2. If no records are newer than the snapshot, rotate the (now-stale)
+ *    journal silently and return.
+ * 3. If records are found, apply the final record's messages — each journal
+ *    record carries the full conversation snapshot at that moment, so the
+ *    last record by seq is the authoritative post-crash state.
+ * 4. Rebuild the conversation history and call the snapshot writer so the
+ *    gap is durably closed before the user sees the restored conversation.
+ * 5. Rotate the journal (it is no longer needed as a gap-filler).
+ * 6. Return a result so the caller can emit an honest notice.
+ */
+
+import { journalPathFor, openTranscriptJournal, replayJournal } from './transcript-journal.ts';
+import type { ConversationManager } from './conversation.ts';
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ReplayIntoConversationOptions {
+  /** Absolute path to the journal file for this session. */
+  readonly journalPath: string;
+  /**
+   * The `timestamp` field from the loaded session snapshot (SessionMeta).
+   * Only journal records with ts > snapshotTimestamp are replayed.
+   */
+  readonly snapshotTimestamp: number;
+  /** The live conversation manager to mutate with replayed messages. */
+  readonly conversation: ConversationManager;
+  /** Session ID — used when creating the post-replay journal instance for rotate(). */
+  readonly sessionId: string;
+  /**
+   * Persist the restored conversation so the gap is durably closed.
+   * Called with the final replayed message list. Best-effort — failures
+   * are swallowed so recovery never hard-fails a resume.
+   */
+  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
+}
+
+export interface ReplayIntoConversationResult {
+  /** Number of journal records that post-dated the snapshot. 0 if nothing to replay. */
+  readonly replayed: number;
+  /** True if the journal tail was corrupt (quarantined). */
+  readonly hadCorruptTail: boolean;
+  /** True if the journal had an unrecognised schema version (quarantined). */
+  readonly hadVersionMismatch: boolean;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Replay journal records newer than `snapshotTimestamp` onto `conversation`.
+ *
+ * Returns a result object so the caller can emit an appropriate notice.
+ * Never throws — all errors are swallowed to preserve the "best-effort"
+ * recovery contract.
+ */
+export function replayJournalIntoConversation(
+  options: ReplayIntoConversationOptions,
+): ReplayIntoConversationResult {
+  const { journalPath, snapshotTimestamp, conversation, sessionId, persistSnapshot } = options;
+
+  try {
+    const { records, hadCorruptTail } = replayJournal(journalPath, snapshotTimestamp);
+
+    // Detect version mismatch: replayJournal quarantines and returns
+    // hadCorruptTail=true + 0 records when the header version is wrong.
+    // We distinguish it from a genuine corrupt tail by checking whether the
+    // journal file still exists (quarantine renames it away in both cases,
+    // so we cannot inspect the header at this point). We surface both cases
+    // through hadCorruptTail to the caller; hadVersionMismatch is derived
+    // from it to give the caller a distinct notice option.
+    const hadVersionMismatch = hadCorruptTail && records.length === 0;
+
+    const journal = openTranscriptJournal(journalPath, sessionId);
+
+    if (records.length === 0) {
+      // Nothing to replay — rotate the (now-stale) journal silently.
+      journal.rotate();
+      return { replayed: 0, hadCorruptTail, hadVersionMismatch };
+    }
+
+    // The last record (highest seq) holds the most recent full conversation
+    // state captured before the crash. Apply it.
+    const lastRecord = records[records.length - 1]!;
+    const replayedMessages = lastRecord.messages as ConversationMessageSnapshot[];
+
+    conversation.fromJSON({
+      messages: replayedMessages as never[],
+    });
+    conversation.rebuildHistory();
+
+    // Write a fresh snapshot so the gap is durably closed even if the
+    // process is killed again before the next turn-complete snapshot.
+    try {
+      persistSnapshot(replayedMessages);
+    } catch {
+      // Best-effort — never hard-fail recovery due to snapshot write failure.
+    }
+
+    // Rotate the journal — it is no longer needed as a gap-filler.
+    journal.rotate();
+
+    return { replayed: records.length, hadCorruptTail, hadVersionMismatch: false };
+  } catch {
+    // Absolute last-resort guard — recovery must never crash a resume.
+    return { replayed: 0, hadCorruptTail: false, hadVersionMismatch: false };
+  }
+}
+
+/**
+ * Build the journal path for a given session and home directory, then call
+ * replayJournalIntoConversation().
+ *
+ * Convenience wrapper used by session-workflow.ts so it does not need to
+ * import journalPathFor directly.
+ */
+export function replayJournalForSession(
+  options: Omit<ReplayIntoConversationOptions, 'journalPath'> & {
+    readonly homeDirectory: string;
+  },
+): ReplayIntoConversationResult {
+  const journalPath = journalPathFor(options.homeDirectory, options.sessionId);
+  return replayJournalIntoConversation({ ...options, journalPath });
+}

package/src/core/stream-event-wiring.ts

@@ -1,6 +1,7 @@
 import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
 import { formatUserFacingErrorLine } from './format-user-error.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 /**
  * Live stream and tool-execution metrics maintained by wireStreamEventMetrics.
@@ -29,9 +30,28 @@ interface StreamOrchestrator {
   readonly streamingOutputTokens: number;
 }
 
-/** Minimal provider surface required for the stream stall watchdog. */
+/** Minimal provider surface required for the stream stall watchdog and failover switching. */
 interface StreamProviderRegistry {
-  getCurrentModel(): { readonly provider: string };
+  getCurrentModel(): { readonly provider: string; readonly registryKey?: string };
+  setCurrentModel(registryKey: string): void;
+}
+
+/**
+ * Minimal fallback-chain node shape returned by ProviderOptimizer.testFallback().
+ * Only the fields consumed by the failover path are declared here.
+ */
+interface FailoverChainNode {
+  readonly position: number;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly capable: boolean;
+}
+
+/** Minimal ProviderOptimizer surface required by the failover path. */
+interface FailoverOptimizer {
+  readonly enabled: boolean;
+  testFallback(profile?: Record<string, unknown>): { readonly chain: readonly FailoverChainNode[] };
+  recordFallbackTransition(from: string, to: string, reason: string): void;
 }
 
 /** Minimal system-message surface required for user-visible notifications. */
@@ -40,6 +60,15 @@ interface StreamSystemMessageRouter {
   low(message: string): void;
 }
 
+/**
+ * Minimal cost lookup surface for attaching cost-delta information to failover notices.
+ * Returns USD-per-1M-token pricing for the given model ID.
+ * The implementation may consult a catalog; if the model is unknown both fields are 0.
+ */
+export interface FailoverCostLookup {
+  getCostFromCatalog(modelId: string): { readonly input: number; readonly output: number };
+}
+
 export interface WireStreamEventMetricsOptions {
   /** The UI runtime event bus (turns + tools sub-buses). */
   readonly events: UiRuntimeEvents;
@@ -56,6 +85,86 @@ export interface WireStreamEventMetricsOptions {
    * so the render closure can read it without a forward-reference issue.
    */
   readonly metrics: StreamMetrics;
+  /**
+   * When provided and enabled, the optimizer is consulted on TURN_ERROR to
+   * attempt the next viable provider before surfacing the error to the user.
+   * When absent or optimizer.enabled is false, behaviour is identical to the
+   * pre-failover baseline: error surfaces immediately via systemMessageRouter.
+   */
+  readonly providerOptimizer?: FailoverOptimizer;
+  /**
+   * Callback the caller provides to re-submit the last user turn on a
+   * different provider after a successful failover switch.  Called only when
+   * the optimizer is enabled and a viable next provider exists in the chain.
+   */
+  readonly retryTurn?: () => void;
+  /**
+   * Optional cost catalog for attaching per-1M-token cost information to
+   * the failover notice.  When provided and both models have non-zero pricing,
+   * the notice includes input and output cost comparisons.  When absent or pricing is
+   * unavailable for either model, the notice honestly states "cost data unavailable".
+   */
+  readonly costLookup?: FailoverCostLookup;
+}
+
+/** Result of wireStreamEventMetrics. */
+export interface WireStreamEventMetricsResult {
+  /** Unsubscribe functions; push into the parent unsubs array for cleanup on exit. */
+  readonly unsubs: ReadonlyArray<() => void>;
+  /**
+   * Clear the per-turn failover visited-provider set.
+   * Call this on every new user submission so the visited set does not bleed
+   * across independent turns (the set is also cleared automatically on
+   * TURN_COMPLETED, but a new submission may arrive before TURN_COMPLETED fires).
+   */
+  readonly clearFailoverVisited: () => void;
+  /**
+   * Register a callback that fires whenever a TURN_ERROR is surfaced to the
+   * user — either immediately (no optimizer) or after chain exhaustion.
+   * Does NOT fire when the optimizer performs a successful automatic failover
+   * (in that case the user sees a [Failover] notice, not an error).
+   * Used by main.ts to activate the one-key retry affordance. The callback
+   * receives exhausted=true when the failover chain was exhausted first, so
+   * the notice can say honestly that a retry reuses the same failed provider.
+   */
+  readonly onErrorSurfaced: (cb: (exhausted: boolean) => void) => void;
+}
+
+/**
+ * Build the cost-delta suffix for a failover notice.
+ *
+ * Extracts the model ID from registry keys (format: `provider:modelId`),
+ * queries the cost catalog for both, and formats a human-readable comparison.
+ * If the lookup is absent or either model returns zero pricing (unknown),
+ * returns an honest "cost data unavailable" suffix instead of fabricating values.
+ *
+ * @param lookup - Optional cost catalog; when absent, returns unavailable notice.
+ * @param fromRegistryKey - Registry key of the provider being abandoned (may be undefined).
+ * @param toRegistryKey - Registry key of the provider being selected.
+ * @returns A parenthesised suffix string or empty string.
+ */
+function buildCostDeltaSuffix(
+  lookup: FailoverCostLookup | undefined,
+  fromRegistryKey: string | undefined,
+  toRegistryKey: string,
+): string {
+  if (!lookup) return '';
+  // Registry key format: `provider:modelId` — modelId may itself contain `:`.
+  const fromModelId = fromRegistryKey ? fromRegistryKey.split(':').slice(1).join(':') : '';
+  const toModelId = toRegistryKey.split(':').slice(1).join(':');
+  const fromCost = fromModelId ? lookup.getCostFromCatalog(fromModelId) : { input: 0, output: 0 };
+  const toCost = lookup.getCostFromCatalog(toModelId);
+  // Report unavailable when either side has zero pricing (unknown model).
+  if (fromCost.input === 0 && fromCost.output === 0 && !fromModelId) {
+    return ' [cost data unavailable]';
+  }
+  const hasFromData = fromCost.input > 0 || fromCost.output > 0;
+  const hasToData = toCost.input > 0 || toCost.output > 0;
+  if (!hasFromData || !hasToData) {
+    return ' [cost data unavailable]';
+  }
+  const fmt = (n: number) => `$${n.toFixed(2)}`;
+  return ` [cost/1M: input ${fmt(fromCost.input)}→${fmt(toCost.input)}, output ${fmt(fromCost.output)}→${fmt(toCost.output)}]`;
 }
 
 /**
@@ -64,8 +173,7 @@ export interface WireStreamEventMetricsOptions {
  * and declares it before render() so both the render closure and the returned
  * event handlers share the same reference.
  *
- * Returns an array of unsubscribe functions; push them into the parent unsubs
- * array so they are cleaned up on exit.
+ * Returns an object with unsubscribe functions and a clearFailoverVisited helper.
  *
  * Responsibilities:
  *   - Track stream start time, delta count, token speed, and TTFT
@@ -75,8 +183,11 @@ export interface WireStreamEventMetricsOptions {
  */
 export function wireStreamEventMetrics(
   options: WireStreamEventMetricsOptions,
-): ReadonlyArray<() => void> {
-  const { events, metrics, orchestrator, providerRegistry, systemMessageRouter, render } = options;
+): WireStreamEventMetricsResult {
+  const {
+    events, metrics, orchestrator, providerRegistry,
+    systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
+  } = options;
 
   const unsubs: Array<() => void> = [];
 
@@ -103,10 +214,85 @@ export function wireStreamEventMetrics(
     metrics.tokenSpeed = elapsed > 0 ? tokenCount / elapsed : 0;
   }));
 
+  // Per-turn visited-provider set: tracks providers already attempted this turn
+  // so failover cannot ping-pong between two mutually-failing providers.
+  // True invariant: at most one retry per provider per turn; exhaustion fires
+  // after the chain is consumed.
+  // Cleared on TURN_COMPLETED (see handler below) and on new user submission
+  // (caller clears via clearFailoverVisited(), wired in main.ts).
+  const failoverVisited = new Set<string>();
+
+  unsubs.push(events.turns.on('TURN_COMPLETED', () => {
+    failoverVisited.clear();
+  }));
+
   unsubs.push(events.turns.on('TURN_ERROR', (event) => {
     const errVal: string = event.error;
+
+    // --- Optimizer-gated failover path ---
+    // When the optimizer is present and enabled, attempt to advance to the next
+    // viable provider in the fallback chain before surfacing the error.  When
+    // the optimizer is absent or disabled, behaviour is identical to baseline:
+    // error surfaces immediately.
+    if (providerOptimizer?.enabled && retryTurn) {
+      const fromProvider = providerRegistry.getCurrentModel().provider;
+      // Mark the failing provider as visited so it will never be selected again
+      // in this turn, even if a second TURN_ERROR arrives (e.g. ping-pong).
+      failoverVisited.add(fromProvider);
+      const result = providerOptimizer.testFallback({});
+      // Find the first capable node that is NOT already visited this turn and
+      // is NOT synthetic. Synthetic nodes are skipped permanently by design:
+      // a synthetic model is itself a fallback ladder over real backends, so
+      // failing over INTO one after a real backend already failed is unsound
+      // double-indirection (it can route straight back to the failed provider).
+      const next = result.chain.find(
+        (node) =>
+          node.capable &&
+          !failoverVisited.has(node.providerId) &&
+          node.providerId !== 'synthetic',
+      );
+
+      if (next) {
+        const toRegistryKey = `${next.providerId}:${next.modelId}`;
+        const errorClass = formatUserFacingErrorLine(errVal);
+        // Capture FROM registry key before switching — needed for cost comparison.
+        const fromRegistryKey = providerRegistry.getCurrentModel().registryKey;
+        try {
+          providerRegistry.setCurrentModel(toRegistryKey);
+        } catch (switchErr) {
+          // Switch failed — fall through to honest error display.
+          logger.debug('failover setCurrentModel failed', { toRegistryKey, error: String(switchErr) });
+          systemMessageRouter.high(`[Error] ${errorClass}`);
+          render();
+          return;
+        }
+        // Record the selected provider as visited before the retry fires so
+        // a subsequent TURN_ERROR from that provider also skips it.
+        failoverVisited.add(next.providerId);
+        providerOptimizer.recordFallbackTransition(fromProvider, next.providerId, errorClass);
+        const costSuffix = buildCostDeltaSuffix(costLookup, fromRegistryKey, toRegistryKey);
+        systemMessageRouter.high(
+          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${costSuffix}`,
+        );
+        render();
+        // Re-submit the last user turn on the new provider.
+        retryTurn();
+        return;
+      }
+
+      // Chain exhausted — all capable candidates have been visited or none exist.
+      systemMessageRouter.high(
+        `[Failover] Chain exhausted — no alternative provider available. Original error: ${formatUserFacingErrorLine(errVal)}`,
+      );
+      notifyErrorSurfaced(true);
+      render();
+      return;
+    }
+
+    // Baseline: optimizer disabled or not wired — surface error immediately.
     const formatted = formatUserFacingErrorLine(errVal);
     systemMessageRouter.high(`[Error] ${formatted}`);
+    notifyErrorSurfaced(false);
     render();
   }));
 
@@ -140,5 +326,11 @@ export function wireStreamEventMetrics(
     metrics.activeToolName = undefined;
   }));
 
-  return unsubs;
+  let _errorSurfacedCb: ((exhausted: boolean) => void) | undefined;
+  function notifyErrorSurfaced(exhausted: boolean) { _errorSurfacedCb?.(exhausted); }
+  return {
+    unsubs,
+    clearFailoverVisited: () => failoverVisited.clear(),
+    onErrorSurfaced: (cb: (exhausted: boolean) => void) => { _errorSurfacedCb = cb; },
+  };
 }