@pellux/goodvibes-tui 0.18.4

package/src/runtime/eval/suites.ts

@@ -0,0 +1,264 @@
+/**
+ * Evaluation Harness — built-in benchmark suites.
+ *
+ * These suites are the stable benchmark set checked in CI.
+ * Scenarios exercise production runtime paths and report real measurements.
+ *
+ * Each scenario's id must be stable across runs — it is used as the
+ * baseline key for regression detection.
+ */
+
+import type { EvalScenario, EvalRawResult } from '@pellux/goodvibes-sdk/platform/runtime/eval/types';
+import { createPerfMonitor } from '../perf/index.ts';
+import { createInitialSurfacePerfState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/surface-perf';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Simulate a synthetic render cycle burst and return timing samples. */
+function syntheticRenderCycles(count: number, targetMs: number): number[] {
+  const durations: number[] = [];
+  for (let i = 0; i < count; i++) {
+    // Simulate deterministic render work proportional to target
+    const durationMs = targetMs * (0.5 + (i / count) * 0.5);
+    durations.push(durationMs);
+  }
+  return durations;
+}
+
+// ── Core Performance Suite ────────────────────────────────────────────────────
+
+/**
+ * Scenarios that validate the PerfMonitor + budget evaluation path.
+ * These use production PerfMonitor instances with real budget definitions.
+ */
+const corePerformanceScenarios: EvalScenario[] = [
+  {
+    id: 'core-perf:render-p95-under-budget',
+    name: 'Frame Render p95 Under Budget',
+    suite: 'core-performance',
+    description:
+      'Verifies that PerfMonitor correctly passes when render p95 stays under the 16ms budget.',
+    tags: ['latency', 'render', 'budget'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      const monitor = createPerfMonitor();
+      const surfacePerf = createInitialSurfacePerfState();
+
+      // Inject fast render cycles (well under budget)
+      const durations = syntheticRenderCycles(60, 8); // 8ms average
+      const cycles = durations.map((durationMs, i) => ({
+        cycleId: i,
+        requestedAt: t0 + i * 16,
+        completedAt: t0 + i * 16 + durationMs,
+        durationMs,
+        overBudget: durationMs > 16,
+      }));
+      surfacePerf.recentCycles = cycles;
+      surfacePerf.heapUsedBytes = 50 * 1024 * 1024; // 50 MiB stable
+
+      const perfReport = monitor.evaluate({
+        surfacePerf,
+        extraMetrics: {
+          'event.queue.depth': 10,
+          'tool.executor.overhead.p95': 2,
+          'compaction.latency.p95': 100,
+          'slo.turn_start.p95': 800,
+          'slo.cancel.p95': 150,
+          'slo.reconnect_recovery.p95': 3000,
+          'slo.permission_decision.p95': 40,
+        },
+      });
+
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        perfReport,
+        safetyViolations: 0,
+      };
+    },
+  },
+
+  {
+    id: 'core-perf:slo-turn-start-latency',
+    name: 'SLO Turn Start Latency Under Budget',
+    suite: 'core-performance',
+    description:
+      'Verifies SLO gate for turn_start.p95 stays under the 2000ms budget.',
+    tags: ['latency', 'slo', 'turn'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      const monitor = createPerfMonitor();
+      const surfacePerf = createInitialSurfacePerfState();
+      surfacePerf.heapUsedBytes = 60 * 1024 * 1024;
+
+      const perfReport = monitor.evaluate({
+        surfacePerf,
+        extraMetrics: {
+          'event.queue.depth': 50,
+          'tool.executor.overhead.p95': 3,
+          'compaction.latency.p95': 200,
+          'slo.turn_start.p95': 1200,
+          'slo.cancel.p95': 200,
+          'slo.reconnect_recovery.p95': 4000,
+          'slo.permission_decision.p95': 60,
+        },
+      });
+
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        perfReport,
+        safetyViolations: 0,
+      };
+    },
+  },
+
+  {
+    id: 'core-perf:memory-growth-stable',
+    name: 'Memory Growth Rate Stable',
+    suite: 'core-performance',
+    description:
+      'Verifies the memory growth budget passes when heap is stable.',
+    tags: ['memory', 'budget'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      const monitor = createPerfMonitor();
+      const surfacePerf = createInitialSurfacePerfState();
+
+      // Simulate two consecutive evaluations with negligible heap growth
+      surfacePerf.heapUsedBytes = 80 * 1024 * 1024;
+      surfacePerf.lastMemorySampleAt = t0 - 60_000; // 1 minute ago
+      monitor.evaluate({ surfacePerf, extraMetrics: {} }); // prime the monitor
+
+      surfacePerf.heapUsedBytes = 80 * 1024 * 1024 + 512 * 1024; // +512 KiB over 1 min
+      surfacePerf.lastMemorySampleAt = t0;
+
+      const perfReport = monitor.evaluate({ surfacePerf, extraMetrics: {} });
+
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        perfReport,
+        safetyViolations: 0,
+      };
+    },
+  },
+];
+
+// ── Safety Baseline Suite ─────────────────────────────────────────────────────
+
+/**
+ * Scenarios that validate safety evaluation paths.
+ * These check that the safety scorer correctly grades clean runs.
+ */
+const safetyBaselineScenarios: EvalScenario[] = [
+  {
+    id: 'safety:clean-run-no-violations',
+    name: 'Clean Run — No Safety Violations',
+    suite: 'safety-baseline',
+    description: 'Verifies a clean scenario run scores 100 on the safety dimension.',
+    tags: ['safety'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        safetyViolations: 0,
+      };
+    },
+  },
+
+  {
+    id: 'safety:recovery-success',
+    name: 'Recovery Path — Succeeded',
+    suite: 'safety-baseline',
+    description: 'Validates that a successfully recovered scenario scores correctly on recovery dimension.',
+    tags: ['safety', 'recovery'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        safetyViolations: 0,
+        recoverySucceeded: true,
+      };
+    },
+  },
+
+  {
+    id: 'safety:recovery-failure-score',
+    name: 'Recovery Path — Failed (Score Validation)',
+    suite: 'safety-baseline',
+    description:
+      'Validates that a failed recovery scenario scores below the recovery floor, ' +
+      'and that the gate correctly flags it.',
+    tags: ['safety', 'recovery'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      // Intentionally reports a failed recovery to exercise the scorer path.
+      // The scenario itself completes; the low recovery score is expected.
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        safetyViolations: 0,
+        recoveryFailed: true,
+      };
+    },
+  },
+];
+
+// ── Cost & Token Suite ────────────────────────────────────────────────────────
+
+const costTokenScenarios: EvalScenario[] = [
+  {
+    id: 'cost:no-token-usage',
+    name: 'No Token Usage (Score = 100)',
+    suite: 'cost-tokens',
+    description:
+      'Verifies that scenarios without token usage receive full cost score.',
+    tags: ['cost'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        safetyViolations: 0,
+      };
+    },
+  },
+
+  {
+    id: 'cost:low-token-usage',
+    name: 'Low Token Usage — Under Target',
+    suite: 'cost-tokens',
+    description:
+      'Validates that minimal token usage stays within the cost budget.',
+    tags: ['cost', 'tokens'],
+    async run(): Promise<EvalRawResult> {
+      const t0 = Date.now();
+      return {
+        completed: true,
+        durationMs: Date.now() - t0,
+        tokens: { input: 500, output: 100 },
+        costUsd: 0.0005, // under $0.001 target
+        safetyViolations: 0,
+      };
+    },
+  },
+];
+
+// ── Registry ──────────────────────────────────────────────────────────────────
+
+/**
+ * All built-in benchmark suites.
+ *
+ * Suite names are stable — used as keys in baselines.
+ */
+export const BUILTIN_SUITES: Record<string, EvalScenario[]> = {
+  'core-performance': corePerformanceScenarios,
+  'safety-baseline': safetyBaselineScenarios,
+  'cost-tokens': costTokenScenarios,
+};
+
+/** Flat list of all built-in scenarios (across all suites). */
+export const ALL_SCENARIOS: EvalScenario[] = Object.values(BUILTIN_SUITES).flat();

package/src/runtime/events/domain-map.ts

@@ -0,0 +1,148 @@
+/**
+ * RuntimeEventMap — master mapping of all typed runtime event types to their payloads.
+ *
+ * Used by RuntimeEventBus for type-safe subscriptions. Combine all domain
+ * discriminated union members into a single flat map keyed by the type string.
+ */
+import type { SessionEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/session';
+import type { TurnEvent } from './turn.ts';
+import type { ProviderEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/providers';
+import type { ToolEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/tools';
+import type { TaskEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/tasks';
+import type { AgentEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/agents';
+import type { WorkflowEvent } from './workflows.ts';
+import type { OrchestrationEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/orchestration';
+import type { CommunicationEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/communication';
+import type { PlannerEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/planner';
+import type { PermissionEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/permissions';
+import type { PluginEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/plugins';
+import type { McpEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/mcp';
+import type { TransportEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/transport';
+import type { CompactionEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/compaction';
+import type { UIEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/ui';
+import type { OpsEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/ops';
+import type { ForensicsEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/forensics';
+import type { SecurityEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/security';
+import type { AutomationEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/automation';
+import type { RouteEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/routes';
+import type { ControlPlaneEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/control-plane';
+import type { DeliveryEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/deliveries';
+import type { WatcherEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/watchers';
+import type { SurfaceEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/surfaces';
+import type { KnowledgeEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/knowledge';
+
+/** Union of all runtime domain events. */
+export type AnyRuntimeEvent =
+  | SessionEvent
+  | TurnEvent
+  | ProviderEvent
+  | ToolEvent
+  | TaskEvent
+  | AgentEvent
+  | WorkflowEvent
+  | OrchestrationEvent
+  | CommunicationEvent
+  | PlannerEvent
+  | PermissionEvent
+  | PluginEvent
+  | McpEvent
+  | TransportEvent
+  | CompactionEvent
+  | UIEvent
+  | OpsEvent
+  | ForensicsEvent
+  | SecurityEvent
+  | AutomationEvent
+  | RouteEvent
+  | ControlPlaneEvent
+  | DeliveryEvent
+  | WatcherEvent
+  | SurfaceEvent
+  | KnowledgeEvent;
+
+/**
+ * Utility type that maps an event type discriminant to its full event shape.
+ *
+ * Example:
+ * ```ts
+ * type Payload = RuntimeEventPayload<'TURN_SUBMITTED'>;
+ * // => { type: 'TURN_SUBMITTED'; turnId: string; prompt: string }
+ * ```
+ */
+export type RuntimeEventPayload<T extends AnyRuntimeEvent['type']> = Extract<
+  AnyRuntimeEvent,
+  { type: T }
+>;
+
+/**
+ * Domain labels for use with domain-scoped subscriptions.
+ *
+ * This is the source-of-truth vocabulary for runtime transport/event surfaces.
+ */
+export const RUNTIME_EVENT_DOMAINS = [
+  'session',
+  'turn',
+  'providers',
+  'tools',
+  'tasks',
+  'agents',
+  'workflows',
+  'orchestration',
+  'communication',
+  'planner',
+  'permissions',
+  'plugins',
+  'mcp',
+  'transport',
+  'compaction',
+  'ui',
+  'ops',
+  'forensics',
+  'security',
+  'automation',
+  'routes',
+  'control-plane',
+  'deliveries',
+  'watchers',
+  'surfaces',
+  'knowledge',
+] as const;
+
+/**
+ * Domain label type for use with domain-scoped subscriptions.
+ */
+export type RuntimeEventDomain = typeof RUNTIME_EVENT_DOMAINS[number];
+
+export function isRuntimeEventDomain(value: string): value is RuntimeEventDomain {
+  return (RUNTIME_EVENT_DOMAINS as readonly string[]).includes(value);
+}
+
+/** Map from domain label to its event union type. */
+export type DomainEventMap = {
+  session: SessionEvent;
+  turn: TurnEvent;
+  providers: ProviderEvent;
+  tools: ToolEvent;
+  tasks: TaskEvent;
+  agents: AgentEvent;
+  workflows: WorkflowEvent;
+  orchestration: OrchestrationEvent;
+  communication: CommunicationEvent;
+  planner: PlannerEvent;
+  permissions: PermissionEvent;
+  plugins: PluginEvent;
+  mcp: McpEvent;
+  transport: TransportEvent;
+  compaction: CompactionEvent;
+  ui: UIEvent;
+  ops: OpsEvent;
+  forensics: ForensicsEvent;
+  security: SecurityEvent;
+  automation: AutomationEvent;
+  routes: RouteEvent;
+  'control-plane': ControlPlaneEvent;
+  deliveries: DeliveryEvent;
+  watchers: WatcherEvent;
+  surfaces: SurfaceEvent;
+  knowledge: KnowledgeEvent;
+};

package/src/runtime/events/index.ts

@@ -0,0 +1,194 @@
+/**
+ * Runtime Events — barrel re-exports and RuntimeEventBus.
+ *
+ * Import from this module to access the typed event system:
+ * ```ts
+ * import { RuntimeEventBus, createEventEnvelope } from '../runtime/events/index.ts';
+ * ```
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { RuntimeEventEnvelope } from '@pellux/goodvibes-sdk/platform/runtime/events/envelope';
+import type { AnyRuntimeEvent, RuntimeEventDomain, DomainEventMap } from './domain-map.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+export type { RuntimeEventEnvelope, EnvelopeContext } from '@pellux/goodvibes-sdk/platform/runtime/events/envelope';
+export { createEventEnvelope } from '@pellux/goodvibes-sdk/platform/runtime/events/envelope';
+export type { SessionEvent, SessionEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/session';
+export type { TurnEvent, TurnEventType } from './turn.ts';
+export type { ProviderEvent, ProviderEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/providers';
+export type { ToolEvent, ToolEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/tools';
+export type { TaskEvent, TaskEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/tasks';
+export type { AgentEvent, AgentEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/agents';
+export type { WorkflowEvent, WorkflowEventType } from './workflows.ts';
+export type { OrchestrationEvent, OrchestrationEventType, OrchestrationTaskContract } from '@pellux/goodvibes-sdk/platform/runtime/events/orchestration';
+export type { CommunicationEvent, CommunicationEventType, CommunicationKind, CommunicationScope } from '@pellux/goodvibes-sdk/platform/runtime/events/communication';
+export type { PlannerEvent, PlannerEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/planner';
+export type { PermissionEvent, PermissionEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/permissions';
+export type { PluginEvent, PluginEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/plugins';
+export type { McpEvent, McpEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/mcp';
+export type { TransportEvent, TransportEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/transport';
+export type { CompactionEvent, CompactionEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/compaction';
+export type { UIEvent, UIEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/ui';
+export type { OpsEvent, OpsEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/ops';
+export { RUNTIME_EVENT_DOMAINS, isRuntimeEventDomain } from './domain-map.ts';
+export type { AnyRuntimeEvent, RuntimeEventPayload, RuntimeEventDomain, DomainEventMap } from './domain-map.ts';
+export type { AutomationEvent, AutomationEventType, AutomationScheduleKind, AutomationExecutionMode, AutomationRunOutcome } from '@pellux/goodvibes-sdk/platform/runtime/events/automation';
+export { AUTOMATION_SCHEDULE_KINDS, AUTOMATION_RUN_OUTCOMES } from '@pellux/goodvibes-sdk/platform/runtime/events/automation';
+export type { RouteEvent, RouteEventType, RouteSurfaceKind, RouteTargetKind } from '@pellux/goodvibes-sdk/platform/runtime/events/routes';
+export { ROUTE_SURFACE_KINDS, ROUTE_TARGET_KINDS } from '@pellux/goodvibes-sdk/platform/runtime/events/routes';
+export type { ControlPlaneEvent, ControlPlaneEventType, ControlPlaneClientKind, ControlPlaneTransportKind, ControlPlanePrincipalKind } from '@pellux/goodvibes-sdk/platform/runtime/events/control-plane';
+export { CONTROL_PLANE_CLIENT_KINDS, CONTROL_PLANE_TRANSPORT_KINDS, CONTROL_PLANE_PRINCIPAL_KINDS } from '@pellux/goodvibes-sdk/platform/runtime/events/control-plane';
+export type { DeliveryEvent, DeliveryEventType, DeliveryKind } from '@pellux/goodvibes-sdk/platform/runtime/events/deliveries';
+export { DELIVERY_KINDS } from '@pellux/goodvibes-sdk/platform/runtime/events/deliveries';
+export type { WatcherEvent, WatcherEventType, WatcherSourceKind } from '@pellux/goodvibes-sdk/platform/runtime/events/watchers';
+export { WATCHER_SOURCE_KINDS } from '@pellux/goodvibes-sdk/platform/runtime/events/watchers';
+export type { SurfaceEvent, SurfaceEventType, SurfaceKind } from '@pellux/goodvibes-sdk/platform/runtime/events/surfaces';
+export { SURFACE_KINDS } from '@pellux/goodvibes-sdk/platform/runtime/events/surfaces';
+export type { KnowledgeEvent, KnowledgeEventType } from '@pellux/goodvibes-sdk/platform/runtime/events/knowledge';
+
+/** Listener callback receiving a fully-formed envelope. */
+export type EnvelopeListener<T extends AnyRuntimeEvent = AnyRuntimeEvent> = (
+  envelope: RuntimeEventEnvelope<T['type'], T>
+) => void;
+
+/**
+ * Maximum listeners per channel before a potential memory leak warning is emitted.
+ *
+ * 100 is a generous threshold for a single event type or domain; normal usage
+ * rarely exceeds single-digit listeners. Exceeding this strongly suggests a
+ * subscriber is being registered without a corresponding unsubscribe.
+ */
+const MAX_LISTENERS = 100;
+
+/**
+ * RuntimeEventBus — typed event bus for domain-structured runtime events.
+ *
+ * Supports two subscription modes:
+ * - `on(eventType, callback)` — subscribe to a specific event type
+ * - `onDomain(domain, callback)` — subscribe to all events in a domain
+ *
+ * All events are wrapped in a RuntimeEventEnvelope providing traceId,
+ * sessionId, timestamps, and source context.
+ *
+ * This is the authoritative event transport for runtime domain signaling.
+ */
+export class RuntimeEventBus {
+  /** Per-event-type listener sets. Keyed by the exact event type string. */
+  private readonly _listeners = new Map<AnyRuntimeEvent['type'], Set<EnvelopeListener>>();
+  /** Per-domain listener sets. Keyed by RuntimeEventDomain. */
+  private readonly _domainListeners = new Map<RuntimeEventDomain, Set<EnvelopeListener>>();
+
+  /**
+   * Subscribe to a specific event type.
+   *
+   * @param eventType - The exact event type string to listen for.
+   * @param callback - Called with the full envelope on each emission.
+   * @returns An unsubscribe function.
+   */
+  public on<T extends AnyRuntimeEvent>(
+    eventType: T['type'],
+    callback: EnvelopeListener<T>
+  ): () => void {
+    if (!this._listeners.has(eventType)) {
+      this._listeners.set(eventType, new Set());
+    }
+    const set = this._listeners.get(eventType)!;
+    set.add(callback as EnvelopeListener);
+    if (set.size > MAX_LISTENERS) {
+      logger.warn('[RuntimeEventBus] possible listener leak detected', {
+        eventType,
+        count: set.size,
+        max: MAX_LISTENERS,
+      });
+    }
+    return () => this._off(eventType, callback as EnvelopeListener);
+  }
+
+  /**
+   * Subscribe to all events in a named domain.
+   *
+   * @param domain - Domain name (e.g. 'turn', 'tools', 'session').
+   * @param callback - Called with the full envelope for each domain event.
+   * @returns An unsubscribe function.
+   */
+  public onDomain<D extends RuntimeEventDomain>(
+    domain: D,
+    callback: EnvelopeListener<DomainEventMap[D]>
+  ): () => void {
+    if (!this._domainListeners.has(domain)) {
+      this._domainListeners.set(domain, new Set());
+    }
+    const set = this._domainListeners.get(domain)!;
+    set.add(callback as EnvelopeListener);
+    if (set.size > MAX_LISTENERS) {
+      logger.warn('[RuntimeEventBus] possible domain listener leak detected', {
+        domain,
+        count: set.size,
+        max: MAX_LISTENERS,
+      });
+    }
+    return () => this._offDomain(domain, callback as EnvelopeListener);
+  }
+
+  /**
+   * Emit a runtime event envelope to all matching per-type and per-domain subscribers.
+   *
+   * @internal Callers MUST use the typed emitter wrapper functions from
+   * `src/runtime/emitters/` rather than calling this method directly.
+   * Direct usage bypasses domain-event type enforcement: TypeScript cannot
+   * statically link the `domain` argument to the `envelope` payload type due
+   * to union complexity limitations (TS2590), meaning mismatched pairs compile
+   * without error.
+   *
+   * @see emitTurnSubmitted, emitToolReceived, etc. in `src/runtime/emitters/`
+   *
+   * @param domain - Domain this event belongs to.
+   * @param envelope - The fully-formed envelope to dispatch.
+   */
+  public emit(
+    domain: RuntimeEventDomain,
+    envelope: RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>
+  ): void {
+    // Dispatch to per-type listeners
+    const typeSet = this._listeners.get(envelope.type);
+    if (typeSet) {
+      for (const handler of typeSet) {
+        try {
+          handler(envelope as RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>);
+        } catch (err) {
+          logger.error('[RuntimeEventBus] listener error', {
+            eventType: envelope.type,
+            error: summarizeError(err),
+          });
+        }
+      }
+    }
+    // Dispatch to per-domain listeners
+    const domainSet = this._domainListeners.get(domain);
+    if (domainSet) {
+      for (const handler of domainSet) {
+        try {
+          handler(envelope as RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>);
+        } catch (err) {
+          logger.error('[RuntimeEventBus] domain listener error', {
+            domain,
+            eventType: envelope.type,
+            error: summarizeError(err),
+          });
+        }
+      }
+    }
+  }
+
+  private _off(eventType: AnyRuntimeEvent['type'], callback: EnvelopeListener): void {
+    const set = this._listeners.get(eventType);
+    set?.delete(callback);
+    if (set?.size === 0) this._listeners.delete(eventType);
+  }
+
+  private _offDomain(domain: RuntimeEventDomain, callback: EnvelopeListener): void {
+    const set = this._domainListeners.get(domain);
+    set?.delete(callback);
+    if (set?.size === 0) this._domainListeners.delete(domain);
+  }
+}

package/src/runtime/events/turn.ts

@@ -0,0 +1,60 @@
+/**
+ * TurnEvent — discriminated union covering all conversation turn lifecycle events.
+ *
+ * Maps to the typed runtime event contract for the  domain.
+ */
+import type { PartialToolCall } from '../../providers/interface.ts';
+
+export type TurnStopReason =
+  | 'completed'
+  | 'empty_response'
+  | 'preflight_failed'
+  | 'context_overflow'
+  | 'provider_exhausted'
+  | 'provider_error'
+  | 'hook_denied'
+  | 'tool_loop_circuit_breaker'
+  | 'cancelled'
+  | 'unexpected_error';
+
+export type TurnEvent =
+  /** User prompt has been submitted for processing. */
+  | { type: 'TURN_SUBMITTED'; turnId: string; prompt: string }
+  /** Preflight checks (context, rate limits, etc.) passed. */
+  | { type: 'PREFLIGHT_OK'; turnId: string }
+  /** Preflight checks failed; turn will not proceed. */
+  | { type: 'PREFLIGHT_FAIL'; turnId: string; reason: string; stopReason: Extract<TurnStopReason, 'preflight_failed' | 'context_overflow'> }
+  /** Streaming response has begun. */
+  | { type: 'STREAM_START'; turnId: string }
+  /** An incremental content chunk arrived from the provider. */
+  | { type: 'STREAM_DELTA'; turnId: string; content: string; accumulated: string; reasoning?: string; toolCalls?: PartialToolCall[] }
+  /** Streaming has ended. */
+  | { type: 'STREAM_END'; turnId: string }
+  /** A provider chat call completed within the current turn iteration. */
+  | {
+    type: 'LLM_RESPONSE_RECEIVED';
+    turnId: string;
+    provider: string;
+    model: string;
+    content: string;
+    toolCallCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+  }
+  /** A batch of tool calls is ready for execution. */
+  | { type: 'TOOL_BATCH_READY'; turnId: string; toolCalls: string[] }
+  /** All tool calls in the current batch have completed. */
+  | { type: 'TOOLS_DONE'; turnId: string }
+  /** Post-processing hooks (WRFC, formatters, etc.) have completed. */
+  | { type: 'POST_HOOKS_DONE'; turnId: string }
+  /** Turn completed successfully with a final response. */
+  | { type: 'TURN_COMPLETED'; turnId: string; response: string; stopReason: Extract<TurnStopReason, 'completed' | 'empty_response'> }
+  /** Turn failed with an error. */
+  | { type: 'TURN_ERROR'; turnId: string; error: string; stopReason: Exclude<TurnStopReason, 'completed' | 'empty_response' | 'cancelled'> }
+  /** Turn was cancelled by the user or system. */
+  | { type: 'TURN_CANCEL'; turnId: string; reason?: string; stopReason: Extract<TurnStopReason, 'cancelled'> };
+
+/** All turn event type literals as a union. */
+export type TurnEventType = TurnEvent['type'];

package/src/runtime/events/workflows.ts

@@ -0,0 +1,17 @@
+/**
+ * WorkflowEvent — discriminated union for WRFC workflow lifecycle events.
+ */
+import type { WrfcState } from '../../agents/wrfc-types.ts';
+
+export type WorkflowEvent =
+  | { type: 'WORKFLOW_CHAIN_CREATED'; chainId: string; task: string }
+  | { type: 'WORKFLOW_STATE_CHANGED'; chainId: string; from: WrfcState; to: WrfcState }
+  | { type: 'WORKFLOW_REVIEW_COMPLETED'; chainId: string; score: number; passed: boolean }
+  | { type: 'WORKFLOW_FIX_ATTEMPTED'; chainId: string; attempt: number; maxAttempts: number }
+  | { type: 'WORKFLOW_GATE_RESULT'; chainId: string; gate: string; passed: boolean }
+  | { type: 'WORKFLOW_CHAIN_PASSED'; chainId: string }
+  | { type: 'WORKFLOW_CHAIN_FAILED'; chainId: string; reason: string }
+  | { type: 'WORKFLOW_AUTO_COMMITTED'; chainId: string; commitHash?: string }
+  | { type: 'WORKFLOW_CASCADE_ABORTED'; chainId: string; reason: string };
+
+export type WorkflowEventType = WorkflowEvent['type'];