@pellux/goodvibes-tui 0.18.4

package/src/runtime/diagnostics/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Diagnostics system — barrel re-exports and factory.
+ *
+ * This module provides the public API for the runtime diagnostics system.
+ * Import from here to access types, providers, and the factory function.
+ *
+ * Usage:
+ * ```ts
+ * import { createDiagnosticsProvider } from '../runtime/diagnostics/index.ts';
+ *
+ * const provider = createDiagnosticsProvider({
+ *   eventBus,
+ *   healthAggregator,
+ *   domains: [...],
+ * });
+ * ```
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+  DiagnosticFilter,
+  DiagnosticLevel,
+  PanelConfig,
+  ToolCallEntry,
+  ToolCallPhase,
+  ToolCallPermission,
+  AgentEntry,
+  AgentDiagnosticState,
+  TaskEntry,
+  EventEntry,
+  DomainStateEntry,
+  RuntimeStateSnapshot,
+  DomainHealthSummary,
+  HealthDashboardData,
+} from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/types';
+export { DEFAULT_BUFFER_LIMIT, DEFAULT_PANEL_CONFIG, applyFilter, appendBounded } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/types';
+
+// ── Action system ────────────────────────────────────────────────────────────
+export type {
+  DiagnosticActionType,
+  DiagnosticActionPermission,
+  DiagnosticActionPayload,
+  DiagnosticAction,
+  HighSeverityDiagnostic,
+  ActionResult,
+  NavigateToEntryCallback,
+  PermissionChecker,
+  DiagnosticActionDispatcherConfig,
+  LoadReplayPayload,
+  RunPolicySimulationPayload,
+  JumpToTaskPayload,
+  JumpToAgentPayload,
+  JumpToToolCallPayload,
+  RetryTaskPayload,
+  CancelTaskPayload,
+  CancelAgentPayload,
+} from './actions.ts';
+export {
+  DiagnosticActionDispatcher,
+  buildLoadReplayAction,
+  buildRunPolicySimulationAction,
+  buildJumpToTaskAction,
+  buildJumpToAgentAction,
+  buildJumpToToolCallAction,
+  buildRetryTaskAction,
+  buildCancelTaskAction,
+  buildCancelAgentAction,
+  diagnosticFromTaskFailure,
+  diagnosticFromAgentFailure,
+  diagnosticFromToolContractViolation,
+  diagnosticFromForensicsRun,
+} from './actions.ts';
+
+// ── Panel data providers ─────────────────────────────────────────────────────
+export { ToolCallsPanel } from './panels/tool-calls.ts';
+export { AgentsPanel } from './panels/agents.ts';
+export { TasksPanel } from './panels/tasks.ts';
+export { EventsPanel } from './panels/events.ts';
+export { StateInspectorPanel } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/panels/state-inspector';
+export type { InspectableDomain } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/panels/state-inspector';
+export { HealthPanel } from './panels/health.ts';
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+export { DiagnosticsProvider } from './provider.ts';
+export type { DiagnosticsProviderConfig, DiagnosticPanelName } from './provider.ts';
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+import { DiagnosticsProvider, type DiagnosticsProviderConfig } from './provider.ts';
+
+/**
+ * Factory function that creates a fully wired DiagnosticsProvider.
+ *
+ * @param config - Configuration including the event bus, health aggregator,
+ *   optional domain adapters, and optional per-panel buffer config.
+ * @returns A ready-to-use DiagnosticsProvider.
+ */
+export function createDiagnosticsProvider(config: DiagnosticsProviderConfig): DiagnosticsProvider {
+  return new DiagnosticsProvider(config);
+}

package/src/runtime/diagnostics/panels/agents.ts

@@ -0,0 +1,252 @@
+/**
+ * Agents diagnostic panel data provider.
+ *
+ * Subscribes to agent lifecycle events via the RuntimeEventBus and maintains
+ * a bounded buffer of AgentEntry records. Provides filtered snapshots
+ * for the agents/cohorts diagnostics panel.
+ *
+ * Tracks state, ownership, blockers, and completion status for each agent.
+ */
+import type { RuntimeEventBus, EnvelopeListener } from '../../events/index.ts';
+import type { AnyRuntimeEvent } from '../../events/domain-map.ts';
+import type { RuntimeEventEnvelope } from '@pellux/goodvibes-sdk/platform/runtime/events/envelope';
+import {
+  type AgentEntry,
+  type AgentDiagnosticState,
+  type DiagnosticFilter,
+  type PanelConfig,
+  DEFAULT_PANEL_CONFIG,
+  applyFilter,
+  appendBounded,
+} from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/types';
+
+/** Internal mutable agent record for in-progress agents. */
+interface MutableAgentRecord {
+  agentId: string;
+  taskId?: string;
+  task: string;
+  state: AgentDiagnosticState;
+  spawnedAt: number;
+  completedAt?: number;
+  durationMs?: number;
+  error?: string;
+  blockedOnCallId?: string;
+  blockedOnTool?: string;
+  traceId: string;
+  sessionId: string;
+}
+
+/**
+ * AgentsPanel — diagnostic data provider for agent lifecycle telemetry.
+ *
+ * Active agents are tracked in a live map; terminal agents are moved
+ * to the history buffer for filtering and display.
+ */
+export class AgentsPanel {
+  private readonly _config: PanelConfig;
+  private readonly _eventBus: RuntimeEventBus;
+  /** Active agents keyed by agentId. */
+  private readonly _active = new Map<string, MutableAgentRecord>();
+  /** Completed agent history (oldest first). */
+  private readonly _history: AgentEntry[] = [];
+  /** Registered change notification callbacks. */
+  private readonly _subscribers = new Set<() => void>();
+  /** Unsubscribe function from the event bus. */
+  private _unsub: (() => void) | null = null;
+
+  constructor(eventBus: RuntimeEventBus, config: PanelConfig = DEFAULT_PANEL_CONFIG) {
+    this._eventBus = eventBus;
+    this._config = config;
+    this._start();
+  }
+
+  private _start(): void {
+    const handler: EnvelopeListener<AnyRuntimeEvent> = (
+      envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>
+    ) => {
+      this._handleEnvelope(envelope);
+    };
+    this._unsub = this._eventBus.onDomain('agents', handler as EnvelopeListener);
+  }
+
+  private _handleEnvelope(
+    envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>
+  ): void {
+    const p = envelope.payload;
+    if (!('type' in p)) return;
+    const type = (p as { type: string }).type;
+    const traceId = envelope.traceId;
+    const sessionId = envelope.sessionId;
+
+    switch (type) {
+      case 'AGENT_SPAWNING': {
+        const evt = p as { type: 'AGENT_SPAWNING'; agentId: string; taskId?: string; task: string };
+        this._active.set(evt.agentId, {
+          agentId: evt.agentId,
+          taskId: evt.taskId,
+          task: evt.task,
+          state: 'spawning',
+          spawnedAt: envelope.ts,
+          traceId,
+          sessionId,
+        });
+        this._notify();
+        break;
+      }
+      case 'AGENT_RUNNING': {
+        const evt = p as { type: 'AGENT_RUNNING'; agentId: string };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'running';
+          record.blockedOnCallId = undefined;
+          record.blockedOnTool = undefined;
+          this._notify();
+        }
+        break;
+      }
+      case 'AGENT_AWAITING_MESSAGE': {
+        const evt = p as { type: 'AGENT_AWAITING_MESSAGE'; agentId: string };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'awaiting_message';
+          this._notify();
+        }
+        break;
+      }
+      case 'AGENT_AWAITING_TOOL': {
+        const evt = p as { type: 'AGENT_AWAITING_TOOL'; agentId: string; callId: string; tool: string };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'awaiting_tool';
+          record.blockedOnCallId = evt.callId;
+          record.blockedOnTool = evt.tool;
+          this._notify();
+        }
+        break;
+      }
+      case 'AGENT_FINALIZING': {
+        const evt = p as { type: 'AGENT_FINALIZING'; agentId: string };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'finalizing';
+          this._notify();
+        }
+        break;
+      }
+      case 'AGENT_COMPLETED': {
+        const evt = p as { type: 'AGENT_COMPLETED'; agentId: string; durationMs: number };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'completed';
+          record.completedAt = envelope.ts;
+          record.durationMs = evt.durationMs;
+          this._finalize(record);
+        }
+        break;
+      }
+      case 'AGENT_FAILED': {
+        const evt = p as { type: 'AGENT_FAILED'; agentId: string; error: string; durationMs: number };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'failed';
+          record.completedAt = envelope.ts;
+          record.durationMs = evt.durationMs;
+          record.error = evt.error;
+          this._finalize(record);
+        }
+        break;
+      }
+      case 'AGENT_CANCELLED': {
+        const evt = p as { type: 'AGENT_CANCELLED'; agentId: string; reason?: string };
+        const record = this._active.get(evt.agentId);
+        if (record) {
+          record.state = 'cancelled';
+          record.completedAt = envelope.ts;
+          record.error = evt.reason;
+          this._finalize(record);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  private _finalize(record: MutableAgentRecord): void {
+    this._active.delete(record.agentId);
+    const entry: AgentEntry = {
+      agentId: record.agentId,
+      taskId: record.taskId,
+      task: record.task,
+      state: record.state,
+      spawnedAt: record.spawnedAt,
+      completedAt: record.completedAt,
+      durationMs: record.durationMs,
+      error: record.error,
+      blockedOnCallId: record.blockedOnCallId,
+      blockedOnTool: record.blockedOnTool,
+      traceId: record.traceId,
+      sessionId: record.sessionId,
+    };
+    appendBounded(this._history, entry, this._config.bufferLimit);
+    this._notify();
+  }
+
+  /**
+   * Return a filtered snapshot combining active agents and completed history.
+   * Ordered most-recent first.
+   *
+   * @param filter - Optional filter to restrict entries.
+   */
+  public getSnapshot(filter?: DiagnosticFilter): AgentEntry[] {
+    const activeEntries: AgentEntry[] = [];
+    for (const record of this._active.values()) {
+      activeEntries.push({
+        agentId: record.agentId,
+        taskId: record.taskId,
+        task: record.task,
+        state: record.state,
+        spawnedAt: record.spawnedAt,
+        completedAt: record.completedAt,
+        durationMs: record.durationMs,
+        error: record.error,
+        blockedOnCallId: record.blockedOnCallId,
+        blockedOnTool: record.blockedOnTool,
+        traceId: record.traceId,
+        sessionId: record.sessionId,
+      });
+    }
+    const combined: AgentEntry[] = [...this._history, ...activeEntries];
+    return applyFilter(combined, filter, (e) => e.spawnedAt);
+  }
+
+  /**
+   * Register a callback invoked whenever the data changes.
+   * @returns An unsubscribe function.
+   */
+  public subscribe(callback: () => void): () => void {
+    this._subscribers.add(callback);
+    return () => this._subscribers.delete(callback);
+  }
+
+  /**
+   * Release all event bus subscriptions and clear internal state.
+   */
+  public dispose(): void {
+    if (this._unsub) {
+      this._unsub();
+      this._unsub = null;
+    }
+    this._subscribers.clear();
+  }
+
+  private _notify(): void {
+    for (const cb of this._subscribers) {
+      try {
+        cb();
+      } catch {
+        // Non-fatal: subscriber errors must not crash the provider
+      }
+    }
+  }
+}

package/src/runtime/diagnostics/panels/events.ts

@@ -0,0 +1,188 @@
+/**
+ * Events diagnostic panel data provider.
+ *
+ * Subscribes to ALL runtime event domains via the RuntimeEventBus and maintains
+ * a bounded buffer of EventEntry records. Provides the typed event timeline
+ * with full trace/session/turn/task/agent correlation context.
+ *
+ * This panel powers the "Events/Diagnostics" view.
+ */
+import type { RuntimeEventBus, EnvelopeListener } from '../../events/index.ts';
+import type { AnyRuntimeEvent, RuntimeEventDomain } from '../../events/domain-map.ts';
+import type { RuntimeEventEnvelope } from '@pellux/goodvibes-sdk/platform/runtime/events/envelope';
+import {
+  type EventEntry,
+  type DiagnosticFilter,
+  type PanelConfig,
+  DEFAULT_PANEL_CONFIG,
+  appendBounded,
+} from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/types';
+
+/** All domains observed by the events panel. */
+const ALL_DOMAINS: readonly RuntimeEventDomain[] = [
+  'session',
+  'turn',
+  'tools',
+  'tasks',
+  'agents',
+  'permissions',
+  'plugins',
+  'mcp',
+  'transport',
+  'compaction',
+  'ui',
+];
+
+/**
+ * Produce a condensed human-readable summary of an event payload.
+ * Extracts the most diagnostic fields without exposing full payloads.
+ */
+function summarizePayload(type: string, payload: unknown): string {
+  if (typeof payload !== 'object' || payload === null) return type;
+  const p = payload as Record<string, unknown>;
+  // Extract common correlation fields for a concise summary line
+  const parts: string[] = [];
+  if (typeof p['tool'] === 'string') parts.push(`tool=${p['tool']}`);
+  if (typeof p['callId'] === 'string') parts.push(`call=${p['callId'].slice(0, 8)}`);
+  if (typeof p['agentId'] === 'string') parts.push(`agent=${p['agentId'].slice(0, 8)}`);
+  if (typeof p['taskId'] === 'string') parts.push(`task=${p['taskId'].slice(0, 8)}`);
+  if (typeof p['error'] === 'string') parts.push(`err=${p['error'].slice(0, 40)}`);
+  if (typeof p['durationMs'] === 'number') parts.push(`${p['durationMs']}ms`);
+  if (typeof p['progress'] === 'number') parts.push(`${p['progress']}%`);
+  return parts.length > 0 ? `${type} ${parts.join(' ')}` : type;
+}
+
+/**
+ * EventsPanel — diagnostic data provider for the full event timeline.
+ *
+ * Captures every envelope emitted across all domains, building a chronological
+ * log with full tracing context. The buffer is bounded to prevent unbounded
+ * memory growth in long-running sessions.
+ */
+export class EventsPanel {
+  private readonly _config: PanelConfig;
+  private readonly _eventBus: RuntimeEventBus;
+  /** Monotonic sequence counter for ordering within a session. */
+  private _seq = 0;
+  /** Event history buffer (oldest first). */
+  private readonly _buffer: EventEntry[] = [];
+  /** Registered change notification callbacks. */
+  private readonly _subscribers = new Set<() => void>();
+  /** Per-domain unsubscribe functions. */
+  private readonly _unsubs: Array<() => void> = [];
+
+  constructor(eventBus: RuntimeEventBus, config: PanelConfig = DEFAULT_PANEL_CONFIG) {
+    this._eventBus = eventBus;
+    this._config = config;
+    this._start();
+  }
+
+  private _start(): void {
+    for (const domain of ALL_DOMAINS) {
+      const d = domain;
+      const handler: EnvelopeListener<AnyRuntimeEvent> = (
+        envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>
+      ) => {
+        this._handleEnvelope(d, envelope);
+      };
+      const unsub = this._eventBus.onDomain(d, handler as EnvelopeListener);
+      this._unsubs.push(unsub);
+    }
+  }
+
+  private _handleEnvelope(
+    domain: RuntimeEventDomain,
+    envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>
+  ): void {
+    const entry: EventEntry = {
+      seq: this._seq++,
+      type: envelope.type,
+      domain,
+      ts: envelope.ts,
+      traceId: envelope.traceId,
+      sessionId: envelope.sessionId,
+      turnId: envelope.turnId,
+      agentId: envelope.agentId,
+      taskId: envelope.taskId,
+      source: envelope.source,
+      summary: summarizePayload(envelope.type, envelope.payload),
+    };
+    appendBounded(this._buffer, entry, this._config.bufferLimit);
+    this._notify();
+  }
+
+  /**
+   * Return a filtered snapshot of event timeline entries.
+   * Ordered most-recent first.
+   *
+   * @param filter - Optional filter. Supports: domains (as `domains` strings),
+   *   since/until time range, traceId/sessionId/turnId/taskId correlation,
+   *   and limit.
+   */
+  public getSnapshot(filter?: DiagnosticFilter): EventEntry[] {
+    let result = [...this._buffer];
+
+    if (filter) {
+      if (filter.domains && filter.domains.length > 0) {
+        const domainSet = new Set(filter.domains);
+        result = result.filter((e) => domainSet.has(e.domain));
+      }
+      if (filter.traceId !== undefined) {
+        result = result.filter((e) => e.traceId === filter.traceId);
+      }
+      if (filter.sessionId !== undefined) {
+        result = result.filter((e) => e.sessionId === filter.sessionId);
+      }
+      if (filter.turnId !== undefined) {
+        result = result.filter((e) => e.turnId === filter.turnId);
+      }
+      if (filter.taskId !== undefined) {
+        result = result.filter((e) => e.taskId === filter.taskId);
+      }
+      if (filter.since !== undefined) {
+        const since = filter.since;
+        result = result.filter((e) => e.ts >= since);
+      }
+      if (filter.until !== undefined) {
+        const until = filter.until;
+        result = result.filter((e) => e.ts <= until);
+      }
+    }
+
+    // Most recent first
+    result.reverse();
+
+    const limit = filter?.limit ?? this._config.bufferLimit;
+    return result.slice(0, limit);
+  }
+
+  /**
+   * Register a callback invoked whenever a new event is captured.
+   * @returns An unsubscribe function.
+   */
+  public subscribe(callback: () => void): () => void {
+    this._subscribers.add(callback);
+    return () => this._subscribers.delete(callback);
+  }
+
+  /**
+   * Release all event bus subscriptions and clear internal state.
+   */
+  public dispose(): void {
+    for (const unsub of this._unsubs) {
+      unsub();
+    }
+    this._unsubs.length = 0;
+    this._subscribers.clear();
+  }
+
+  private _notify(): void {
+    for (const cb of this._subscribers) {
+      try {
+        cb();
+      } catch {
+        // Non-fatal: subscriber errors must not crash the provider
+      }
+    }
+  }
+}