@pellux/goodvibes-agent 1.4.4 → 1.5.0

package/src/core/last-seen-store.ts

@@ -0,0 +1,78 @@
+/**
+ * LastSeenStore — persists the timestamp of the user's last TUI session.
+ *
+ * Used by the away-digest feature to know what happened since the user was
+ * last present. Follows the same file-backed JSON pattern as the agent
+ * registries (see src/agent/routine-registry.ts).
+ *
+ * File layout:
+ *   { version: 1, lastSeenAt: <epoch-ms> }
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+
+interface LastSeenFile {
+  readonly version: 1;
+  readonly lastSeenAt: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function parseFile(raw: string): LastSeenFile | null {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed)) return null;
+    if (parsed['version'] !== 1) return null;
+    const ts = parsed['lastSeenAt'];
+    if (typeof ts !== 'number' || !Number.isFinite(ts) || ts <= 0) return null;
+    return { version: 1, lastSeenAt: ts };
+  } catch {
+    return null;
+  }
+}
+
+type AgentLocalStorePaths = Pick<ShellPathService, 'resolveUserPath'>;
+
+export function lastSeenStorePath(shellPaths: AgentLocalStorePaths): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'last-seen.json');
+}
+
+export class LastSeenStore {
+  public constructor(private readonly storePath: string) {}
+
+  public static fromShellPaths(shellPaths: AgentLocalStorePaths): LastSeenStore {
+    return new LastSeenStore(lastSeenStorePath(shellPaths));
+  }
+
+  /**
+   * Read the persisted lastSeenAt value.
+   * Returns null when the file doesn't exist or is corrupt (first run).
+   */
+  public read(): number | null {
+    try {
+      const raw = readFileSync(this.storePath, 'utf-8');
+      return parseFile(raw)?.lastSeenAt ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Persist the current time as the new lastSeenAt.
+   * Silently ignores write errors to avoid crashing on shutdown.
+   */
+  public save(at: number = Date.now()): void {
+    try {
+      mkdirSync(dirname(this.storePath), { recursive: true });
+      const data: LastSeenFile = { version: 1, lastSeenAt: at };
+      writeFileSync(this.storePath, JSON.stringify(data, null, 2), 'utf-8');
+    } catch {
+      // Silently ignore — last-seen is a best-effort hint, not critical state.
+    }
+  }
+}

package/src/core/plain-language.ts

@@ -0,0 +1,52 @@
+/**
+ * Plain-language vocabulary gate.
+ *
+ * Exports the banned-term lists and a validate helper so that the release-gate
+ * test and any future caller share a single definition.
+ *
+ * WHY EACH TERM IS BANNED
+ * ───────────────────────
+ * FIRST_GLANCE_BANNED — terms the user sees on labels, summaries, and action
+ * labels (the copy they read without clicking through). These must never appear
+ * in first-glance copy because they are internal implementation vocabulary that
+ * a non-technical user would not understand or would find confusing:
+ *
+ *   WRFC        — internal code-review workflow acronym, never user-facing
+ *   daemon      — Unix process jargon; user-facing name is "assistant service"
+ *   posture     — internal policy/config term; meaningless to end users
+ *   modelRoute  — internal routing key; end users pick a "model", not a "route"
+ *   agent_harness — raw tool identifier; end users never see tool names
+ *   action:"   — raw tool parameter syntax that leaks protocol details
+ *   mode:"     — raw tool parameter syntax that leaks protocol details
+ *   cli         — developer-facing term; never appears on operator UX labels
+ *
+ * EVERYWHERE_BANNED — terms that must not appear even in action detail copy
+ * (which technical users may read after clicking through):
+ *
+ *   WRFC        — internal workflow acronym with no end-user meaning
+ *   modelRoute  — internal routing key never intended for user-facing copy
+ */
+
+export const FIRST_GLANCE_BANNED: readonly RegExp[] = [
+  /\bWRFC\b/,
+  /\bdaemon\b/i,
+  /\bposture\b/i,
+  /\bmodelRoute\b/,
+  /\bagent_harness\b/,
+  /action:"/,
+  /mode:"/,
+  /\bcli\b/i,
+];
+
+export const EVERYWHERE_BANNED: readonly RegExp[] = [
+  /\bWRFC\b/,
+  /\bmodelRoute\b/,
+];
+
+/**
+ * Return the subset of rules that match `text`.
+ * Returns an empty array when there are no violations.
+ */
+export function validate(text: string, rules: readonly RegExp[]): RegExp[] {
+  return rules.filter((rule) => rule.test(text));
+}

package/src/core/setup-incomplete-hint.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure builder for the "setup not finished" hint shown once at startup
+ * when the user has started but not completed onboarding.
+ *
+ * No side effects, no imports from the runtime or shell — testable in isolation.
+ */
+
+import type { OnboardingState } from '../runtime/onboarding/onboarding-state.ts';
+
+export interface SetupIncompleteHintResult {
+  readonly lines: string[];
+}
+
+/**
+ * Build a plain-language hint reminding the user that setup isn't finished
+ * and pointing them at /agent.
+ *
+ * Returns null when:
+ * - phase === 'complete'  — setup is done, no nag needed
+ * - phase === 'fresh'     — first-run users get the full workspace, not a nag
+ *
+ * Only phase === 'in-progress' produces a hint (the user has opened /agent
+ * at least once but hasn't finished).
+ *
+ * @param state     The current OnboardingState (from deriveOnboardingState).
+ * @param hostReady True = assistant service is reachable; false = not yet running;
+ *                  null/undefined = unknown (omit the host line entirely).
+ */
+export function buildSetupIncompleteHint(
+  state: OnboardingState,
+  hostReady?: boolean | null,
+): SetupIncompleteHintResult | null {
+  if (state.phase !== 'in-progress') return null;
+
+  const lines: string[] = [];
+
+  // ── Line 1: readiness / chat availability ────────────────────────────────
+  if (!state.readyToChat) {
+    // Model not configured — that's the most urgent thing.
+    lines.push('Pick a model to start — run /agent to continue setup.');
+  } else {
+    // Chat works but setup isn't done.
+    // NOTE: progressLabel is intentionally omitted here — the hint's plan may be
+    // a reduced subset of the full setup plan, so any 'N of M' count would
+    // misrepresent real progress and mislead the user.
+    const nextStep = pickNextStep(state);
+    if (nextStep) {
+      lines.push(
+        `You can chat now. Still finishing setup — ${nextStep} — run /agent to complete it.`,
+      );
+    } else {
+      lines.push(
+        'You can chat now. Some background features still need setup — run /agent to finish.',
+      );
+    }
+  }
+
+  // ── Line 2 (optional): assistant service / background work status ─────────
+  // Only append when the caller has a reliable live signal. Never fabricate.
+  if (hostReady === true) {
+    lines.push('Background work (reminders, schedules) is active.');
+  } else if (hostReady === false) {
+    lines.push('Background work (reminders, schedules) is not running yet.');
+  }
+  // hostReady === null or undefined → omit line entirely.
+
+  return { lines };
+}
+
+/**
+ * Pick the single most actionable next-step phrase from the state.
+ * Prefers the first autonomy-blocking step, then the first non-ready step.
+ * Returns undefined when no useful step hint is available.
+ */
+function pickNextStep(state: OnboardingState): string | undefined {
+  const step =
+    state.blockers[0] ??
+    state.steps.find((s) => s.status !== 'ready');
+
+  if (!step) return undefined;
+
+  // Use the step's nextLabel if it reads like plain language (no slash syntax).
+  // Fall back to the step's label.
+  const label = step.nextLabel && !step.nextLabel.startsWith('/') && !step.nextLabel.includes('action:')
+    ? step.nextLabel
+    : step.label;
+
+  // Truncate to keep the hint compact (max ~60 chars for the next-step phrase).
+  return label.length > 60 ? `${label.slice(0, 58)}…` : label;
+}

package/src/core/system-message-router.ts

@@ -1,37 +1,25 @@
 /**
- * SystemMessageRouter — routes system messages to the appropriate surfaces
- * based on priority.
+ * SystemMessageRouter — routes system messages to the right surfaces.
  *
- * Two tiers:
- *   - 'high' — appears in both the main conversation AND the SystemMessagesPanel.
- *     Use for: fatal errors, model/provider confirmations, session save/load,
- *     compaction events (e.g. [Compaction] completed).
- *   - 'low'  — appears in the SystemMessagesPanel only (panel-only routing).
- *     Use for: scan results, provider discovery, plugin load/unload, feature
- *     flag changes, tool execution status, permission decisions,
- *     health/cascade events, debug/operational info.
- *
- * Usage:
- * ```ts
- * const router = createSystemMessageRouter(conversation, panel);
- * router.routeSystemMessage('[Provider] anthropic registered', 'low');
- * router.routeSystemMessage('[Session] Saved session abc123', 'high');
- * ```
+ * Every message lands in the ActivityFeed (the ambient "Recent" record shown
+ * in the Activity sidebar). High-priority messages — errors, confirmations the
+ * user explicitly caused, session lifecycle — additionally land in the main
+ * conversation so they are impossible to miss.
  *
- * The router can also be used as a drop-in replacement for
- * conversation.addSystemMessage() calls — it classifies messages by priority
- * automatically when using routeAuto().
+ * Two tiers:
+ *   - 'high' — conversation AND activity feed. Use for: fatal errors,
+ *     model/provider confirmations, session save/load, compaction events.
+ *   - 'low'  — activity feed only. Use for: scan results, provider discovery,
+ *     plugin load/unload, tool execution status, permission decisions,
+ *     health events, debug/operational info.
  *
- * @remarks
- * This router handles system messages (operational status, errors). It is
- * distinct from NotificationRouter which handles domain-specific typed
- * notifications with policy-based routing.
+ * The `ui.systemMessages` / `ui.operationalMessages` settings keep their
+ * historical values ('panel' | 'conversation' | 'both'); 'panel' now means
+ * "activity feed only".
  */
 
-import { getConfigSnapshot } from '../config/index.ts';
-import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConversationManager } from './conversation';
-import type { SystemMessagesPanel, SystemMessagePriority } from '../panels/system-messages-panel.ts';
+import type { ActivityFeed } from './activity-feed.ts';
 import {
   classifySystemMessageKind,
   classifySystemMessagePriority,
@@ -46,51 +34,30 @@ export type {
   SystemMessageTarget,
 } from '@/runtime/index.ts';
 
-function targetForKind(
-  configManager: Pick<ConfigManager, 'getRaw'>,
-  kind: SystemMessageKind,
-): SystemMessageTarget {
-  const ui = getConfigSnapshot(configManager).ui;
-  if (kind === 'wrfc') return ui.wrfcMessages;
-  if (kind === 'operational') return ui.operationalMessages;
-  return ui.systemMessages;
-}
-
-// ---------------------------------------------------------------------------
-// SystemMessageRouter
-// ---------------------------------------------------------------------------
+export type SystemMessagePriority = 'high' | 'low';
 
 /**
- * Routes system messages to the conversation and/or the SystemMessagesPanel
- * based on priority level.
+ * Routes system messages to the conversation and/or the ActivityFeed
+ * based on priority level and per-kind targets.
  */
 export class SystemMessageRouter {
   constructor(
     private readonly conversation: ConversationManager,
-    private panel: SystemMessagesPanel | null,
+    private feed: ActivityFeed | null,
     private readonly getTargetForKind: (kind: SystemMessageKind) => SystemMessageTarget = defaultSystemMessageTarget,
   ) {}
 
-  // ── Public API ────────────────────────────────────────────────────────────
+  // ── Public API ────────────────────────────────────────────────────────────────
 
-  /**
-   * Route a system message with explicit priority.
-   *
-   * - 'high': delivered to both conversation AND panel.
-   * - 'low':  delivered to panel only (conversation is not touched).
-   *
-   * @param message  - Message text.
-   * @param priority - 'high' | 'low'.
-   */
   routeTypedSystemMessage(
     message: string,
     priority: SystemMessagePriority,
     kind: SystemMessageKind,
   ): void {
     const target = this.getTargetForKind(kind);
-    const delivery = resolveSystemMessageDelivery(target, this.panel !== null);
+    const delivery = resolveSystemMessageDelivery(target, this.feed !== null);
     if (delivery.toPanel) {
-      this.panel?.push(message, priority);
+      this.feed?.push(message, priority);
     }
     if (delivery.toConversation) {
       this.conversation.addSystemMessage(message);
@@ -103,29 +70,19 @@ export class SystemMessageRouter {
 
   /**
    * Automatically classify the message priority by content and route.
-   *
-   * Useful as a drop-in replacement for conversation.addSystemMessage()
-   * when you want the router to determine priority.
-   *
-   * @param message - Message text.
+   * Drop-in replacement for conversation.addSystemMessage().
    */
   routeAuto(message: string): void {
     const priority: SystemMessagePriority = classifySystemMessagePriority(message);
     this.routeTypedSystemMessage(message, priority, classifySystemMessageKind(message));
   }
 
-  /**
-   * High-priority convenience shortcut.
-   * Equivalent to routeSystemMessage(message, 'high').
-   */
+  /** High-priority shortcut — conversation + activity feed. */
   high(message: string): void {
     this.routeSystemMessage(message, 'high');
   }
 
-  /**
-   * Low-priority convenience shortcut.
-   * Equivalent to routeSystemMessage(message, 'low').
-   */
+  /** Low-priority shortcut — activity feed only. */
   low(message: string): void {
     this.routeSystemMessage(message, 'low');
   }
@@ -134,38 +91,32 @@ export class SystemMessageRouter {
     this.routeTypedSystemMessage(message, priority, 'wrfc');
   }
 
-  /**
-   * Returns the current panel reference.
-   */
-  getPanel(): SystemMessagesPanel | null {
-    return this.panel;
+  /** Returns the current activity feed reference. */
+  getFeed(): ActivityFeed | null {
+    return this.feed;
   }
 
   /**
-   * Replace the panel reference after construction (late binding).
-   * Pass null to detach the panel.
+   * Replace the feed reference after construction (late binding).
+   * Pass null to detach.
    */
-  setPanel(panel: SystemMessagesPanel | null): void {
-    this.panel = panel;
+  setFeed(feed: ActivityFeed | null): void {
+    this.feed = feed;
   }
 }
 
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
 /**
- * Create a SystemMessageRouter wired to the given conversation and panel.
+ * Create a SystemMessageRouter wired to the given conversation and feed.
  *
  * @param conversation - The ConversationManager for high-priority messages.
- * @param panel        - The SystemMessagesPanel for all messages. Can be null
- *                       (router still works; messages to panel are silently
- *                       dropped until a panel is available).
+ * @param feed         - The ActivityFeed for ambient traffic. Can be null
+ *                       (router still works; feed routing is dropped until
+ *                       a feed is attached).
  */
 export function createSystemMessageRouter(
   conversation: ConversationManager,
-  panel: SystemMessagesPanel | null = null,
+  feed: ActivityFeed | null = null,
   getTargetForKind: (kind: SystemMessageKind) => SystemMessageTarget = defaultSystemMessageTarget,
 ): SystemMessageRouter {
-  return new SystemMessageRouter(conversation, panel, getTargetForKind);
+  return new SystemMessageRouter(conversation, feed, getTargetForKind);
 }