@pellux/goodvibes-tui 0.22.0 → 0.23.0

package/src/renderer/compaction-preview.ts

@@ -0,0 +1,146 @@
+/**
+ * Compaction preview and after-notice builders.
+ *
+ * Pre-compact: shows an honest estimate of what compaction will do
+ * (message count and token estimate before → after). The SDK has no dry-run
+ * API; we derive the after-estimate from the DEFAULT_COMPACTION_CONFIG
+ * totalCeiling (6500 tokens) — clearly labelled as an ESTIMATE.
+ *
+ * Post-compact: shows a before/after notice using the CompactionEvent
+ * data returned by compactMessages(), which contains the real
+ * tokensBeforeEstimate and tokensAfterEstimate figures.
+ *
+ * Honest wording policy:
+ *  - Pre-compact notice says "estimate" every time; never claims certainty.
+ *  - Post-compact notice uses "~N" prefix on every token figure.
+ *  - Pinned session memories that survive are mentioned by count.
+ */
+
+import { estimateConversationTokens } from '@pellux/goodvibes-sdk/platform/core';
+import type { CompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
+import type { ProviderMessage } from '@pellux/goodvibes-sdk/platform/providers';
+
+/**
+ * Default compaction totalCeiling from context-compaction DEFAULT_COMPACTION_CONFIG.
+ * Kept local so we don't take a runtime dependency on the internal config object.
+ * Used only for the pre-compact ESTIMATE; the real figure comes from CompactionEvent.
+ */
+const COMPACTION_OUTPUT_CEILING_ESTIMATE = 6500;
+
+export interface CompactionPreviewOptions {
+  /** Messages currently in the conversation. */
+  readonly messages: readonly ProviderMessage[];
+  /** Context window size for the current model (0 if unknown). */
+  readonly contextWindow: number;
+  /** Number of session memories that will survive compaction. */
+  readonly pinnedMemoryCount: number;
+  /** Whether this is triggered automatically or manually. */
+  readonly trigger: 'auto' | 'manual';
+}
+
+export interface CompactionAfterOptions {
+  /** The CompactionEvent returned by the SDK after compaction completes. */
+  readonly event: CompactionEvent;
+  /** Number of session memories that survived compaction. */
+  readonly pinnedMemoryCount: number;
+}
+
+/**
+ * Build the pre-compaction notice string.
+ *
+ * Returned as a plain string intended for `ctx.print()` or `systemMessageRouter`.
+ * Always labelled as an estimate; uses the SDK totalCeiling as the after-estimate.
+ */
+export function buildCompactionPreview(opts: CompactionPreviewOptions): string {
+  const { messages, contextWindow, pinnedMemoryCount, trigger } = opts;
+  const msgCount = messages.length;
+  const tokensBefore = estimateConversationTokens(messages as ProviderMessage[]);
+  const tokensAfterEstimate = COMPACTION_OUTPUT_CEILING_ESTIMATE;
+
+  const contextStr = contextWindow > 0
+    ? ` (${Math.round((tokensBefore / contextWindow) * 100)}% of ${fmtN(contextWindow)} context window)`
+    : '';
+
+  const pinStr = pinnedMemoryCount > 0
+    ? ` ${pinnedMemoryCount} pinned session memor${pinnedMemoryCount === 1 ? 'y' : 'ies'} will be preserved.`
+    : '';
+
+  const triggerStr = trigger === 'auto' ? 'Auto-compacting' : 'Compacting';
+
+  return (
+    `[Context] ${triggerStr} conversation: ~${fmtN(tokensBefore)} tokens across ${msgCount} message${msgCount === 1 ? '' : 's'}${contextStr}.` +
+    ` Estimated result: ~${fmtN(tokensAfterEstimate)} tokens (estimate — actual depends on content).` +
+    (pinStr ? ` ${pinStr.trim()}` : '')
+  );
+}
+
+/**
+ * Build the post-compaction before/after notice string.
+ *
+ * Uses the real CompactionEvent figures (not estimates) for both before and
+ * after token counts. The trigger field controls wording.
+ */
+export function buildCompactionAfterNotice(opts: CompactionAfterOptions): string {
+  const { event, pinnedMemoryCount } = opts;
+  const {
+    messagesBeforeCompaction,
+    messagesAfterCompaction,
+    tokensBeforeEstimate,
+    tokensAfterEstimate,
+    trigger,
+  } = event;
+
+  const savings = Math.max(0, tokensBeforeEstimate - tokensAfterEstimate);
+  const savingsPct = tokensBeforeEstimate > 0
+    ? Math.round((savings / tokensBeforeEstimate) * 100)
+    : 0;
+
+  const pinStr = pinnedMemoryCount > 0
+    ? ` ${pinnedMemoryCount} pinned memor${pinnedMemoryCount === 1 ? 'y' : 'ies'} preserved.`
+    : '';
+
+  const triggerStr = trigger === 'auto' ? 'Auto-compact complete' : 'Compact complete';
+
+  return (
+    `[Context] ${triggerStr}: ${messagesBeforeCompaction} → ${messagesAfterCompaction} messages,` +
+    ` ~${fmtN(tokensBeforeEstimate)} → ~${fmtN(tokensAfterEstimate)} tokens` +
+    ` (saved ~${fmtN(savings)}, ${savingsPct}%).` +
+    (pinStr ? ` ${pinStr.trim()}` : '')
+  );
+}
+
+/** Format a number with thousands separators. */
+function fmtN(n: number): string {
+  return n.toLocaleString();
+}
+
+/**
+ * Build the /keep command usage text (shown when no args are provided).
+ *
+ * Exported for testability — the shell-core handler renders this string directly.
+ */
+export function buildPinUsageText(): string {
+  return (
+    '[Pin] Usage: /keep <text>\n' +
+    'Pinned entries are stored as session memories and included in the compaction handoff as pinned memories.\n' +
+    'What pinning guarantees: the text survives the next compaction.\n' +
+    'What pinning does NOT guarantee: recovery after process restart (session memories are in-memory only).'
+  );
+}
+
+/**
+ * Build the /keep command success text.
+ *
+ * @param id - The assigned memory ID (e.g. "mem-1")
+ * @param text - The pinned text
+ * @param count - Total pinned memory count after adding
+ *
+ * Exported for testability — the shell-core handler renders this string directly.
+ */
+export function buildPinSuccessText(id: string, text: string, count: number): string {
+  return (
+    `[Pin] Pinned as ${id}: "${text.slice(0, 60)}${text.length > 60 ? '...' : ''}"\n` +
+    `  ${count} pinned memor${count === 1 ? 'y' : 'ies'} will survive the next compaction.\n` +
+    '  Note: session memories are in-memory only and do not persist across restarts.'
+  );
+}

package/src/renderer/settings-modal-helpers.ts

@@ -4,8 +4,8 @@
  * architecture cap. No layout logic lives here.
  */
 
-import type { SettingEntry, McpEntry, SubscriptionEntry } from '../input/settings-modal.ts';
-import { SETTINGS_CATEGORIES } from '../input/settings-modal.ts';
+import type { SettingEntry, McpEntry, SubscriptionEntry } from '../input/settings-modal-types.ts';
+import { SETTINGS_CATEGORIES } from '../input/settings-modal-types.ts';
 import { isSecretConfigKey, isSecretReferenceValue } from '../config/secret-config.ts';
 
 function maskSecretValue(value: string): string {

package/src/runtime/bootstrap-core.ts

@@ -123,6 +123,88 @@ export interface BootstrapCoreState {
 
 export type CompanionMessagePayload = Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>;
 
+// ---------------------------------------------------------------------------
+// Operator narration of inbound channel events
+// ---------------------------------------------------------------------------
+
+/**
+ * Narrate an inbound channel event to the operator via the SystemMessageRouter.
+ *
+ * When an external surface (GitHub, Slack, ntfy, etc.) triggers an agent turn,
+ * this function produces a human-readable system message so the operator can
+ * observe which event caused the turn. Returns null for internal/companion
+ * sources that do not need operator narration.
+ *
+ * @param event - The normalized inbound event descriptor.
+ * @returns A narration string, or null if no narration is appropriate.
+ */
+export function narrateInboundEvent(event: {
+  source: string;
+  metadata: Readonly<Record<string, unknown>> | undefined;
+}): string | null {
+  const { source, metadata } = event;
+  if (!source) return null;
+
+  // Derive the effective surface — prefer metadata.surface, fall back to source.
+  const surface = typeof metadata?.surface === 'string' ? metadata.surface : source;
+
+  // Internal / companion sources do not need operator narration.
+  if (surface === 'companion' || source === 'companion') return null;
+  if (surface === 'internal' || source === 'internal') return null;
+
+  // Build a surface label for the log prefix.
+  const label = ((): string => {
+    switch (surface) {
+      case 'github':        return '[GitHub]';
+      case 'slack':         return '[Slack]';
+      case 'discord':       return '[Discord]';
+      case 'ntfy':          return '[ntfy]';
+      case 'homeassistant': return '[HomeAssistant]';
+      case 'telegram':      return '[Telegram]';
+      case 'google-chat':   return '[Google Chat]';
+      case 'signal':        return '[Signal]';
+      case 'whatsapp':      return '[WhatsApp]';
+      case 'msteams':       return '[Teams]';
+      case 'imessage':      return '[iMessage]';
+      case 'bluebubbles':   return '[BlueBubbles]';
+      case 'mattermost':    return '[Mattermost]';
+      case 'matrix':        return '[Matrix]';
+      case 'webhook':       return '[Webhook]';
+      default:              return `[${surface[0]!.toUpperCase()}${surface.slice(1)}]`;
+    }
+  })();
+
+  const eventType   = typeof metadata?.eventType   === 'string' ? metadata.eventType   : null;
+  const eventAction = typeof metadata?.eventAction  === 'string' ? metadata.eventAction : null;
+  const topic       = typeof metadata?.topic        === 'string' ? metadata.topic       : null;
+  const prNumber    = typeof metadata?.prNumber     === 'number' ? metadata.prNumber    : null;
+  const issueNumber = typeof metadata?.issueNumber  === 'number' ? metadata.issueNumber : null;
+  const repo        = typeof metadata?.repo         === 'string' ? metadata.repo        : null;
+
+  // Build event-specific detail for GitHub events.
+  if (surface === 'github' && eventType) {
+    const actionPart = eventAction ? ` ${eventAction}` : '';
+    let detail = `${eventType}${actionPart} → agent triggered`;
+    if (prNumber !== null) {
+      detail = `PR #${prNumber}${repo ? ` (${repo})` : ''} ${eventAction ?? eventType} → agent triggered`;
+    } else if (issueNumber !== null) {
+      detail = `Issue #${issueNumber}${repo ? ` (${repo})` : ''} ${eventAction ?? eventType} → agent triggered`;
+    } else if (repo) {
+      detail = `${eventType}${actionPart} in ${repo} → agent triggered`;
+    }
+    return `${label} ${detail}`;
+  }
+
+  // ntfy: include topic when available.
+  if (surface === 'ntfy' && topic) {
+    return `${label} inbound message on topic '${topic}' → agent triggered`;
+  }
+
+  // Generic narration for all other surfaces.
+  const eventDetail = eventType ? ` ${eventType}${eventAction ? ` ${eventAction}` : ''}` : '';
+  return `${label}${eventDetail} inbound event → agent triggered`;
+}
+
 export function companionMessageToOrchestratorInputOptions(
   payload: CompanionMessagePayload,
 ): OrchestratorUserInputOptions {
@@ -525,6 +607,16 @@ export async function initializeBootstrapCore(
   runtimeUnsubs.push(runtimeBus.on<Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>>(
     'COMPANION_MESSAGE_RECEIVED',
     ({ payload }) => {
+      // Narrate inbound external events to the operator so they can observe
+      // which channel event triggered the agent turn.
+      const narration = narrateInboundEvent({
+        source: payload.source,
+        metadata: payload.metadata,
+      });
+      if (narration) {
+        routeOrBuffer(narration, 'low');
+      }
+
       if (orchestratorHandleUserInputRef.value) {
         // Delegate to the orchestrator: adds user message + fires a real LLM turn.
         // Preserve surface origin metadata so the SDK can correlate replies back

package/src/utils/browser.ts

@@ -0,0 +1,29 @@
+/**
+ * browser.ts — cross-platform browser launcher utility.
+ *
+ * Extracted from cli/management.ts so it can be used by input-layer commands
+ * without creating an upward cli→input dependency. Lives in utils (Layer 0)
+ * and has no imports from shell-UI or entrypoint layers.
+ */
+
+import { spawn } from 'node:child_process';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+/**
+ * Open the given URL in the user's default browser.
+ * Returns a status string (success or error description).
+ * Does not throw — errors are returned as a descriptive string.
+ */
+export function openBrowser(url: string): string {
+  const platform = process.platform;
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.once('error', () => {});
+    child.unref();
+    return 'browser open requested';
+  } catch (error) {
+    return `browser open failed: ${summarizeError(error)}`;
+  }
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.22.0';
+let _version = '0.23.0';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;