@pellux/goodvibes-tui 0.21.0 → 0.23.0

package/src/panels/cockpit-read-model.ts

@@ -0,0 +1,232 @@
+// ---------------------------------------------------------------------------
+// cockpit-read-model.ts
+//
+// TASK-046: Cockpit agent roster slice + cost/token aggregates + stalledAgentCount
+//
+// Provides a thin read-model over AgentManager.list() / getStatus() so the
+// CockpitPanel can display an agent roster without depending on the full
+// AgentInspectorPanel object.
+//
+// Design notes:
+//   - Per-agent cost delegates to calcSessionCost() from cost-utils.ts (canonical
+//     billing formula) and requires real usage data from AgentRecord.usage.  When
+//     usage is absent (agent spawned but not yet completed), cost/tokens show as n/a
+//     rather than fabricated values (39327f86 honest-UX standard).
+//   - stalledAgentCount delegates to countStalledAgents() from agent-inspector-shared.ts
+//     (canonical stall-count function extracted from TASK-046 review) — no reimplementation.
+//   - The read-model is a plain object (snapshot + subscribe) so it can be
+//     wired in tests without a full runtime.
+// ---------------------------------------------------------------------------
+
+import type { AgentRecord } from '@pellux/goodvibes-sdk/platform/tools';
+import { calcSessionCost } from '../export/cost-utils.ts';
+import {
+  AGENT_TERMINAL_STATUSES,
+  AGENT_STALL_THRESHOLD_MS,
+  countStalledAgents,
+} from './agent-inspector-shared.ts';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Status of a single agent in the cockpit roster. */
+export type CockpitAgentStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+/** A single row in the cockpit agent roster. */
+export interface CockpitAgentRosterEntry {
+  /** Full agent id. */
+  readonly id: string;
+  /** Short task description (truncated at 50 chars). */
+  readonly task: string;
+  /** Model identifier, or 'unknown' when not yet resolved. */
+  readonly model: string;
+  /** Agent lifecycle status. */
+  readonly status: CockpitAgentStatus;
+  /** True when the agent is non-terminal and has exceeded AGENT_STALL_THRESHOLD_MS. */
+  readonly stalled: boolean;
+  /** Input tokens consumed (including cache read+write), or null when unavailable. */
+  readonly inputTokens: number | null;
+  /** Output tokens produced, or null when unavailable. */
+  readonly outputTokens: number | null;
+  /** Estimated cost in USD, or null when token data is unavailable. */
+  readonly cost: number | null;
+}
+
+/** Aggregate snapshot produced by the cockpit roster read-model. */
+export interface CockpitRosterSnapshot {
+  /** All agents in the manager, newest-first by startedAt. */
+  readonly roster: readonly CockpitAgentRosterEntry[];
+  /** Number of non-terminal agents running past AGENT_STALL_THRESHOLD_MS. */
+  readonly stalledAgentCount: number;
+  /**
+   * Sum of all input tokens across agents with real usage data.
+   * null when NO agent has usage data yet (avoids showing 0 when data is simply absent).
+   */
+  readonly totalInputTokens: number | null;
+  /**
+   * Sum of all output tokens across agents with real usage data.
+   * null when NO agent has usage data yet.
+   */
+  readonly totalOutputTokens: number | null;
+  /**
+   * Total estimated cost in USD across agents with real pricing data.
+   * null when NO agent has priceable data yet.
+   */
+  readonly totalCost: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// AgentManager minimal interface (subset used here)
+// ---------------------------------------------------------------------------
+
+export interface CockpitRosterAgentManager {
+  list(): AgentRecord[];
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot builder — pure, testable
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a CockpitRosterSnapshot from a raw AgentRecord list.
+ * Exported so unit tests can drive it directly without a manager stub.
+ */
+export function buildCockpitRosterSnapshot(
+  records: AgentRecord[],
+  now: number = Date.now(),
+): CockpitRosterSnapshot {
+  // Sort newest-first by startedAt
+  const sorted = [...records].sort((a, b) => b.startedAt - a.startedAt);
+
+  let hasUsage = false;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalCost = 0;
+
+  const roster: CockpitAgentRosterEntry[] = sorted.map((rec) => {
+    const isTerminal = AGENT_TERMINAL_STATUSES.has(rec.status);
+    const elapsed = now - rec.startedAt;
+    const stalled = !isTerminal && elapsed >= AGENT_STALL_THRESHOLD_MS;
+
+    let inputTokens: number | null = null;
+    let outputTokens: number | null = null;
+    let cost: number | null = null;
+
+    if (rec.usage) {
+      hasUsage = true;
+      const inp =
+        rec.usage.inputTokens +
+        (rec.usage.cacheReadTokens ?? 0) +
+        (rec.usage.cacheWriteTokens ?? 0);
+      const out = rec.usage.outputTokens;
+      const agentCost = calcSessionCost(
+        rec.usage.inputTokens,
+        rec.usage.outputTokens,
+        rec.usage.cacheReadTokens ?? 0,
+        rec.usage.cacheWriteTokens ?? 0,
+        rec.model ?? 'unknown',
+      );
+
+      inputTokens = inp;
+      outputTokens = out;
+      cost = agentCost;
+
+      totalInputTokens += inp;
+      totalOutputTokens += out;
+      totalCost += agentCost;
+    }
+
+    const task = rec.task.length > 50 ? rec.task.slice(0, 47) + '...' : rec.task;
+
+    return {
+      id: rec.id,
+      task,
+      model: rec.model ?? 'unknown',
+      status: rec.status,
+      stalled,
+      inputTokens,
+      outputTokens,
+      cost,
+    };
+  });
+
+  return {
+    roster,
+    stalledAgentCount: countStalledAgents(sorted, now),
+    totalInputTokens: hasUsage ? totalInputTokens : null,
+    totalOutputTokens: hasUsage ? totalOutputTokens : null,
+    totalCost: hasUsage ? totalCost : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Read-model factory
+// ---------------------------------------------------------------------------
+
+/** Minimal read-model interface matching the existing UiReadModel shape. */
+export interface CockpitRosterReadModel {
+  getSnapshot(): CockpitRosterSnapshot;
+  /**
+   * Notify all subscribers that the roster has changed and the cockpit panel
+   * should re-render.  Wire this to an AgentManager event feed so live agent
+   * state changes propagate:
+   *
+   *   const roster = createCockpitRosterReadModel(agentManager);
+   *   agentEvents.subscribe(() => roster.markDirty());
+   *
+   * For static/test fixtures the implementation is a no-op.
+   */
+  markDirty(): void;
+  /**
+   * Subscribe to changes.  The listener is called whenever markDirty() is
+   * invoked.  Returns an unsubscribe function.
+   *
+   * For static/test fixtures, returns a no-op unsubscribe.
+   */
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Create a live CockpitRosterReadModel backed by an AgentManager.
+ *
+ * The returned read-model re-derives its snapshot on every getSnapshot() call
+ * so it always reflects the current agent state without needing an event bus.
+ * Callers that want reactive updates should poll or wire in their own
+ * event-driven markDirty() path.
+ */
+export function createCockpitRosterReadModel(
+  agentManager: CockpitRosterAgentManager,
+): CockpitRosterReadModel {
+  const listeners = new Set<() => void>();
+
+  function markDirty(): void {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  return {
+    getSnapshot(): CockpitRosterSnapshot {
+      return buildCockpitRosterSnapshot(agentManager.list());
+    },
+    markDirty,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+/**
+ * Create a static CockpitRosterReadModel for testing.
+ */
+export function createStaticCockpitRosterReadModel(
+  snapshot: CockpitRosterSnapshot,
+): CockpitRosterReadModel {
+  return {
+    getSnapshot: () => snapshot,
+    markDirty: () => {},
+    subscribe: () => () => {},
+  };
+}

package/src/panels/index.ts

@@ -40,7 +40,7 @@ export { SecurityPanel } from './security-panel.ts';
 export { MarketplacePanel } from './marketplace-panel.ts';
 export { SandboxPanel } from './sandbox-panel.ts';
 export { ApprovalPanel } from './approval-panel.ts';
-export { KnowledgePanel } from './knowledge-panel.ts';
+export { KnowledgeGraphPanel } from './knowledge-graph-panel.ts';
 export { SystemMessagesPanel } from './system-messages-panel.ts';
 export { PanelListPanel } from './panel-list-panel.ts';
 export type { SystemMessageEntry, SystemMessagePriority } from './system-messages-panel.ts';

package/src/panels/knowledge-graph-panel.ts

@@ -0,0 +1,84 @@
+/**
+ * KnowledgeGraphPanel — SDK knowledge graph front-door.
+ *
+ * TASK-040: The 'knowledge' panel id is repointed here (the SDK graph), fixing
+ * the naming inversion where the former panel named 'Knowledge' was actually
+ * rendering memory records.
+ *
+ * This panel is a thin information surface that explains the graph's capabilities
+ * and routes the user to the /knowledge command suite for ingest/RAG operations.
+ * The full graph UI is command-driven (/knowledge ask, ingest-url, list, search…).
+ */
+
+import type { Line } from '../types/grid.ts';
+import { BasePanel } from './base-panel.ts';
+import {
+  buildBodyText,
+  buildGuidanceLine,
+  buildPanelLine,
+  buildPanelWorkspace,
+  DEFAULT_PANEL_PALETTE,
+} from './polish.ts';
+
+const C = {
+  ...DEFAULT_PANEL_PALETTE,
+  header: '#94a3b8',
+  headerBg: '#1e293b',
+} as const;
+
+export class KnowledgeGraphPanel extends BasePanel {
+  constructor() {
+    super('knowledge', 'Knowledge', 'K', 'agent');
+  }
+
+  handleInput(_key: string): boolean {
+    return false;
+  }
+
+  render(width: number, height: number): Line[] {
+    const sections = [
+      {
+        title: 'SDK Knowledge Graph',
+        lines: [
+          ...buildBodyText(
+            width,
+            'The knowledge graph stores ingested URLs, bookmarks, and structured facts as nodes and edges. ' +
+            'Use /knowledge commands to ingest sources, search the graph, and build task-context packets.',
+            C,
+            C.value,
+          ),
+          buildPanelLine(width, [['', C.dim]]),
+          buildGuidanceLine(width, '/knowledge status', 'check the graph status and source counts', C),
+          buildGuidanceLine(width, '/knowledge ask <query>', 'ask a question against the ingested knowledge', C),
+          buildGuidanceLine(width, '/knowledge ingest-url <url>', 'ingest a URL as a knowledge source', C),
+          buildGuidanceLine(width, '/knowledge list', 'list ingested sources or graph nodes', C),
+          buildGuidanceLine(width, '/knowledge search <query>', 'search the graph for nodes and sources', C),
+          buildGuidanceLine(width, '/knowledge packet <task>', 'build a compact prompt packet for a task', C),
+        ],
+      },
+      {
+        title: 'Project Memory',
+        lines: [
+          ...buildBodyText(
+            width,
+            'For durable decisions, risks, runbooks, incidents, and architecture records, use the Memory panel ' +
+            'or the /recall command surface. Durable memory is a sub-namespace of the knowledge graph.',
+            C,
+            C.dim,
+          ),
+          buildPanelLine(width, [['', C.dim]]),
+          buildGuidanceLine(width, '/recall add <class> <summary>', 'capture a new memory record', C),
+          buildGuidanceLine(width, '/recall queue', 'show the operator review queue', C),
+          buildGuidanceLine(width, '/project-memory (pmem)', 'project-memory alias for /recall front-door', C),
+        ],
+      },
+    ];
+
+    return buildPanelWorkspace(width, height, {
+      title: 'Knowledge Graph',
+      intro: 'Ingested sources, graph nodes, and the durable memory bridge.',
+      sections,
+      palette: C,
+    });
+  }
+}