@pellux/goodvibes-agent 0.1.0

package/src/runtime/cloudflare-control-plane.ts

@@ -0,0 +1,349 @@
+import { join } from 'node:path';
+import { getOrCreateCompanionToken } from '@pellux/goodvibes-sdk/platform/pairing';
+import type { ConfigManager } from '../config/index.ts';
+
+export const CLOUDFLARE_COMPONENT_IDS = [
+  'workers',
+  'queues',
+  'zeroTrustTunnel',
+  'zeroTrustAccess',
+  'dns',
+  'kv',
+  'durableObjects',
+  'secretsStore',
+  'r2',
+] as const;
+
+export type CloudflareComponent = typeof CLOUDFLARE_COMPONENT_IDS[number];
+export type CloudflareComponentSelection = Partial<Record<CloudflareComponent, boolean>>;
+export type CloudflareBatchMode = 'off' | 'explicit' | 'eligible-by-default';
+
+export const DEFAULT_CLOUDFLARE_COMPONENT_SELECTION: Readonly<Record<CloudflareComponent, boolean>> = {
+  workers: true,
+  queues: true,
+  zeroTrustTunnel: false,
+  zeroTrustAccess: false,
+  dns: false,
+  kv: false,
+  durableObjects: false,
+  secretsStore: false,
+  r2: false,
+};
+
+export const CLOUDFLARE_COMPONENT_LABELS: Readonly<Record<CloudflareComponent, string>> = {
+  workers: 'Workers',
+  queues: 'Queues',
+  zeroTrustTunnel: 'Zero Trust Tunnel',
+  zeroTrustAccess: 'Zero Trust Access',
+  dns: 'DNS hostname',
+  kv: 'KV',
+  durableObjects: 'Durable Objects',
+  secretsStore: 'Secrets Store',
+  r2: 'R2 artifacts',
+};
+
+export interface CloudflareProvisionStep {
+  readonly name: string;
+  readonly status: 'ok' | 'skipped' | 'warning';
+  readonly message?: string;
+  readonly resourceId?: string;
+}
+
+export interface CloudflareControlPlaneStatus {
+  readonly enabled: boolean;
+  readonly ready: boolean;
+  readonly configured: Record<string, boolean>;
+  readonly config: Record<string, unknown>;
+  readonly warnings: readonly string[];
+}
+
+export interface CloudflareTokenRequirement {
+  readonly component: CloudflareComponent | 'bootstrap';
+  readonly scope: 'account' | 'zone' | 'user' | 'r2';
+  readonly permission: string;
+  readonly alternatives?: readonly string[];
+  readonly reason: string;
+}
+
+export interface CloudflareTokenRequirementsResult {
+  readonly ok: true;
+  readonly components: Readonly<Record<CloudflareComponent, boolean>>;
+  readonly permissions: readonly CloudflareTokenRequirement[];
+  readonly bootstrapToken: {
+    readonly requiredForSdkCreation: boolean;
+    readonly storeInGoodVibes: false;
+    readonly instructions: readonly string[];
+  };
+}
+
+export interface CloudflareValidateResult {
+  readonly ok: boolean;
+  readonly account?: {
+    readonly id: string;
+    readonly name: string;
+    readonly type?: string;
+  };
+  readonly tokenSource: string;
+}
+
+export interface CloudflareOperationalTokenResult {
+  readonly ok: true;
+  readonly tokenId?: string;
+  readonly tokenName: string;
+  readonly tokenSource: 'bootstrap';
+  readonly apiTokenRef?: string;
+  readonly generatedToken?: string;
+  readonly accountId: string;
+  readonly zoneId?: string;
+  readonly permissions: readonly CloudflareTokenRequirement[];
+}
+
+export interface CloudflareDiscoverResult {
+  readonly ok: true;
+  readonly tokenSource: string;
+  readonly accounts: ReadonlyArray<{ readonly id: string; readonly name: string; readonly type?: string }>;
+  readonly selectedAccount?: { readonly id: string; readonly name: string; readonly type?: string };
+  readonly zones: ReadonlyArray<{ readonly id: string; readonly name: string; readonly status?: string; readonly type?: string }>;
+  readonly selectedZone?: { readonly id: string; readonly name: string; readonly status?: string; readonly type?: string };
+  readonly workerSubdomain?: string;
+  readonly queues?: ReadonlyArray<{ readonly queue_id?: string; readonly queue_name?: string }>;
+  readonly kvNamespaces?: ReadonlyArray<{ readonly id?: string; readonly title?: string }>;
+  readonly durableObjectNamespaces?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly class?: string }>;
+  readonly r2Buckets?: ReadonlyArray<{ readonly name?: string; readonly storage_class?: string }>;
+  readonly secretsStores?: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  readonly tunnels?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly status?: string }>;
+  readonly accessApplications?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly domain?: string; readonly type?: string }>;
+  readonly warnings: readonly string[];
+}
+
+export interface CloudflareProvisionResult {
+  readonly ok: boolean;
+  readonly dryRun: false;
+  readonly steps: readonly CloudflareProvisionStep[];
+  readonly account?: { readonly id: string; readonly name: string };
+  readonly worker?: { readonly name: string; readonly baseUrl?: string; readonly subdomain?: string; readonly hostname?: string; readonly cron?: string };
+  readonly queues?: { readonly queueName: string; readonly queueId: string; readonly deadLetterQueueName: string; readonly deadLetterQueueId: string; readonly consumerId?: string };
+  readonly tunnel?: { readonly id: string; readonly name: string; readonly hostname?: string; readonly tokenRef?: string };
+  readonly access?: { readonly appId?: string; readonly serviceTokenId?: string; readonly serviceTokenRef?: string };
+  readonly dns?: {
+    readonly zoneId: string;
+    readonly zoneName?: string;
+    readonly records: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly type?: string; readonly content?: string }>;
+  };
+  readonly kv?: { readonly namespaceName: string; readonly namespaceId: string };
+  readonly durableObjects?: { readonly namespaceName: string; readonly namespaceId?: string };
+  readonly r2?: { readonly bucketName: string; readonly storageClass: 'Standard' };
+  readonly secretsStore?: { readonly storeName: string; readonly storeId: string };
+  readonly verification?: CloudflareVerifyResult;
+  readonly generatedSecrets?: {
+    readonly workerClientToken?: string;
+    readonly tunnelToken?: string;
+    readonly accessServiceTokenClientId?: string;
+    readonly accessServiceTokenClientSecret?: string;
+  };
+}
+
+export interface CloudflareVerifyResult {
+  readonly ok: boolean;
+  readonly workerHealth: {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly error?: string;
+  };
+  readonly daemonBatchProxy?: {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly error?: string;
+  };
+}
+
+export interface CloudflareDisableResult {
+  readonly ok: boolean;
+  readonly steps: readonly CloudflareProvisionStep[];
+}
+
+export interface CloudflareTokenRequirementsRequest {
+  readonly components?: CloudflareComponentSelection;
+  readonly includeBootstrap?: boolean;
+}
+
+export interface CloudflareOperationalTokenRequest extends CloudflareTokenRequirementsRequest {
+  readonly accountId?: string;
+  readonly zoneId?: string;
+  readonly zoneName?: string;
+  readonly bootstrapToken?: string;
+  readonly tokenName?: string;
+  readonly expiresOn?: string;
+  readonly persistConfig?: boolean;
+  readonly storeApiToken?: boolean;
+  readonly returnGeneratedToken?: boolean;
+}
+
+export interface CloudflareValidateRequest {
+  readonly accountId?: string;
+  readonly apiToken?: string;
+  readonly apiTokenRef?: string;
+}
+
+export interface CloudflareDiscoverRequest extends CloudflareValidateRequest {
+  readonly components?: CloudflareComponentSelection;
+  readonly zoneId?: string;
+  readonly zoneName?: string;
+  readonly includeResources?: boolean;
+}
+
+export interface CloudflareProvisionRequest extends CloudflareDiscoverRequest {
+  readonly workerName?: string;
+  readonly workerSubdomain?: string;
+  readonly workerHostname?: string;
+  readonly workerBaseUrl?: string;
+  readonly daemonBaseUrl?: string;
+  readonly daemonHostname?: string;
+  readonly queueName?: string;
+  readonly deadLetterQueueName?: string;
+  readonly tunnelName?: string;
+  readonly tunnelId?: string;
+  readonly tunnelServiceUrl?: string;
+  readonly tunnelTokenRef?: string;
+  readonly accessAppId?: string;
+  readonly accessServiceTokenId?: string;
+  readonly accessServiceTokenRef?: string;
+  readonly kvNamespaceName?: string;
+  readonly kvNamespaceId?: string;
+  readonly durableObjectNamespaceName?: string;
+  readonly durableObjectNamespaceId?: string;
+  readonly r2BucketName?: string;
+  readonly secretsStoreName?: string;
+  readonly secretsStoreId?: string;
+  readonly workerCron?: string;
+  readonly operatorToken?: string;
+  readonly operatorTokenRef?: string;
+  readonly workerClientToken?: string;
+  readonly workerClientTokenRef?: string;
+  readonly storeApiToken?: boolean;
+  readonly storeOperatorToken?: boolean;
+  readonly storeWorkerClientToken?: boolean;
+  readonly returnGeneratedSecrets?: boolean;
+  readonly enableWorkersDev?: boolean;
+  readonly queueJobPayloads?: boolean;
+  readonly verify?: boolean;
+  readonly persistConfig?: boolean;
+  readonly batchMode?: CloudflareBatchMode;
+}
+
+export interface CloudflareVerifyRequest {
+  readonly workerBaseUrl?: string;
+  readonly workerClientToken?: string;
+  readonly workerClientTokenRef?: string;
+}
+
+export interface CloudflareDisableRequest extends CloudflareValidateRequest {
+  readonly workerName?: string;
+  readonly disableWorkerSubdomain?: boolean;
+  readonly disableCron?: boolean;
+  readonly persistConfig?: boolean;
+}
+
+export class CloudflareDaemonRouteError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(message: string, status: number, code: string) {
+    super(message);
+    this.name = 'CloudflareDaemonRouteError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export interface CloudflareDaemonClient {
+  status(): Promise<CloudflareControlPlaneStatus>;
+  tokenRequirements(input?: CloudflareTokenRequirementsRequest): Promise<CloudflareTokenRequirementsResult>;
+  createOperationalToken(input: CloudflareOperationalTokenRequest): Promise<CloudflareOperationalTokenResult>;
+  discover(input?: CloudflareDiscoverRequest): Promise<CloudflareDiscoverResult>;
+  validate(input?: CloudflareValidateRequest): Promise<CloudflareValidateResult>;
+  provision(input: CloudflareProvisionRequest): Promise<CloudflareProvisionResult>;
+  verify(input?: CloudflareVerifyRequest): Promise<CloudflareVerifyResult>;
+  disable(input?: CloudflareDisableRequest): Promise<CloudflareDisableResult>;
+}
+
+export interface CloudflareDaemonClientOptions {
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly homeDirectory: string;
+}
+
+function connectHostForBindHost(host: string): string {
+  if (host === '0.0.0.0' || host === '::' || host.trim().length === 0) return '127.0.0.1';
+  return host;
+}
+
+function hostForUrl(host: string): string {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+export function resolveCloudflareDaemonBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
+  const configuredBaseUrl = String(configManager.get('controlPlane.baseUrl' as never) ?? '').trim();
+  if (configuredBaseUrl) return configuredBaseUrl.replace(/\/+$/, '');
+  const host = hostForUrl(connectHostForBindHost(String(configManager.get('controlPlane.host' as never) ?? '127.0.0.1')));
+  const portValue = Number(configManager.get('controlPlane.port' as never) ?? 3421);
+  const port = Number.isFinite(portValue) && portValue > 0 ? portValue : 3421;
+  return `http://${host}:${port}`;
+}
+
+export function buildDefaultCloudflareDaemonBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
+  return resolveCloudflareDaemonBaseUrl(configManager);
+}
+
+function readDaemonToken(homeDirectory: string): string {
+  const daemonHomeDir = join(homeDirectory, '.goodvibes', 'daemon');
+  return getOrCreateCompanionToken('tui', { daemonHomeDir }).token;
+}
+
+async function readJsonResponse<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  const body = text.trim().length > 0 ? JSON.parse(text) as unknown : {};
+  if (!response.ok) {
+    const record = body && typeof body === 'object' ? body as Record<string, unknown> : {};
+    const message = typeof record.error === 'string' ? record.error : `Cloudflare daemon route failed with HTTP ${response.status}`;
+    const code = typeof record.code === 'string' ? record.code : 'CLOUDFLARE_DAEMON_ROUTE_ERROR';
+    throw new CloudflareDaemonRouteError(message, response.status, code);
+  }
+  return body as T;
+}
+
+export function createCloudflareDaemonClient(options: CloudflareDaemonClientOptions): CloudflareDaemonClient {
+  const baseUrl = resolveCloudflareDaemonBaseUrl(options.configManager);
+  const token = readDaemonToken(options.homeDirectory);
+
+  const requestJson = async <T>(path: string, init: RequestInit = {}): Promise<T> => {
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${token}`);
+    if (init.body !== undefined) headers.set('Content-Type', 'application/json');
+    const response = await fetch(`${baseUrl}${path}`, { ...init, headers });
+    return await readJsonResponse<T>(response);
+  };
+
+  const postJson = <T>(path: string, body: unknown): Promise<T> => requestJson<T>(path, {
+    method: 'POST',
+    body: JSON.stringify(body ?? {}),
+  });
+
+  return {
+    status: () => requestJson<CloudflareControlPlaneStatus>('/api/cloudflare/status'),
+    tokenRequirements: (input = {}) => postJson<CloudflareTokenRequirementsResult>('/api/cloudflare/token/requirements', input),
+    createOperationalToken: (input) => postJson<CloudflareOperationalTokenResult>('/api/cloudflare/token/create', input),
+    discover: (input = {}) => postJson<CloudflareDiscoverResult>('/api/cloudflare/discover', input),
+    validate: (input = {}) => postJson<CloudflareValidateResult>('/api/cloudflare/validate', input),
+    provision: (input) => postJson<CloudflareProvisionResult>('/api/cloudflare/provision', input),
+    verify: (input = {}) => postJson<CloudflareVerifyResult>('/api/cloudflare/verify', input),
+    disable: (input = {}) => postJson<CloudflareDisableResult>('/api/cloudflare/disable', input),
+  };
+}
+
+export function normalizeCloudflareComponents(selection: CloudflareComponentSelection | undefined): Record<CloudflareComponent, boolean> {
+  const result: Record<CloudflareComponent, boolean> = { ...DEFAULT_CLOUDFLARE_COMPONENT_SELECTION };
+  for (const component of CLOUDFLARE_COMPONENT_IDS) {
+    if (typeof selection?.[component] === 'boolean') result[component] = selection[component] === true;
+  }
+  return result;
+}

package/src/runtime/context.ts

@@ -0,0 +1,142 @@
+/**
+ * RuntimeContext — the composition root object returned by bootstrapRuntime().
+ *
+ * main.ts receives this and uses it to drive the render loop, input handling,
+ * and terminal lifecycle. The bootstrap owns initialization; main.ts owns
+ * the runtime loop.
+ */
+import type { ConversationManager } from '../core/conversation';
+import type { Orchestrator } from '../core/orchestrator';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { PermissionManager } from '@pellux/goodvibes-sdk/platform/permissions';
+import type { HookDispatcher } from '@pellux/goodvibes-sdk/platform/hooks';
+import type { FileStateCache } from '@pellux/goodvibes-sdk/platform/state';
+import type { ProjectIndex } from '@pellux/goodvibes-sdk/platform/state';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { RuntimeStore } from './store/index.ts';
+import type { RuntimeEventBus } from '@/runtime/index.ts';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
+import type { MutableRuntimeState } from '@/runtime/index.ts';
+import type { SessionSnapshot } from '@/runtime/index.ts';
+import type { RuntimeServices } from './services.ts';
+import type { ComponentHealthMonitor } from './perf/panel-health-monitor.ts';
+import type { WorktreeRegistry } from '@/runtime/index.ts';
+import type { SandboxSessionRegistry } from '@/runtime/index.ts';
+
+/**
+ * Options accepted by bootstrapRuntime().
+ */
+export interface BootstrapOptions {
+  /** App-owned working directory for this runtime instance. */
+  workingDir: string;
+  /** App-owned home directory for this runtime instance. */
+  homeDirectory: string;
+  /** Explicit app-owned config manager for this runtime instance. */
+  configManager: import('@pellux/goodvibes-sdk/platform/config').ConfigManager;
+  /**
+   * Callback invoked when the app should exit.
+   * If provided, commandContext.exit is wired during bootstrap.
+   * Otherwise main.ts binds the shell-owned exit bridge immediately after bootstrap returns.
+   */
+  exit?: () => void;
+}
+
+/**
+ * The fully-initialized runtime context produced by bootstrapRuntime().
+ *
+ * main.ts destructures this to obtain what it needs for the render loop
+ * and input handling.
+ */
+export interface RuntimeContext {
+  // ── Core subsystems ─────────────────────────────────────────────────
+
+  /**
+   * Typed domain event bus for new runtime subsystems.
+   */
+  runtimeBus: RuntimeEventBus;
+
+  /**
+   * Zustand vanilla store for domain state slices.
+   */
+  store: RuntimeStore;
+
+  /**
+   * App-scoped runtime services graph shared across adapters and shells.
+   */
+  services: RuntimeServices;
+
+  /**
+   * Feature flag and kill-switch manager.
+   * Gates runtime subsystems and release controls.
+   */
+  featureFlags: FeatureFlagManager;
+
+  // ── Managers ────────────────────────────────────────────────────────
+
+  /** Manages conversation history and message rendering. */
+  conversation: ConversationManager;
+
+  /** Controls tool execution approval flow. */
+  permissions: PermissionManager;
+
+  /** Registry of all registered tool implementations. */
+  toolRegistry: ToolRegistry;
+
+  // ── Provider ────────────────────────────────────────────────────────
+
+  /** Shared provider registry owned by the runtime services graph. */
+  providerRegistry: ProviderRegistry;
+
+  /** Shared component-health monitor owned by the runtime services graph. */
+  componentHealthMonitor: ComponentHealthMonitor;
+
+  /** Shared worktree registry owned by the runtime services graph. */
+  worktreeRegistry: WorktreeRegistry;
+
+  /** Shared sandbox session registry owned by the runtime services graph. */
+  sandboxSessionRegistry: SandboxSessionRegistry;
+
+  // ── Infrastructure ──────────────────────────────────────────────────
+
+  /** Fires lifecycle hooks registered by the user or plugins. */
+  hookDispatcher: HookDispatcher;
+
+  // ── State ───────────────────────────────────────────────────────────
+
+  /** File read/write cache shared across read/write/edit tools in a session. */
+  fileCache: FileStateCache;
+
+  /** Project-level file index shared across tools. */
+  projectIndex: ProjectIndex;
+
+  // ── Session ─────────────────────────────────────────────────────────
+
+  /** Unique identifier for this user session (hex, prefixed "user-"). */
+  sessionId: string;
+
+  /** True if a previous session was resumed at startup. */
+  isResumed: boolean;
+
+  // ── Mutable runtime state ───────────────────────────────────────────
+
+  /** Mutable model/provider/prompt state closed over by event handlers. */
+  runtime: MutableRuntimeState;
+
+  // ── Orchestrator ─────────────────────────────────────────────────────
+
+  /**
+   * Main LLM orchestrator. Drives the conversation loop, tool execution,
+   * streaming, and context compaction.
+   */
+  orchestrator: Orchestrator;
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  /**
+   * Logical shutdown: save session, fire hooks, stop background managers.
+   * Does NOT touch the terminal — main.ts owns terminal teardown.
+   *
+   * @param sessionData - Latest conversation data to persist.
+   */
+  shutdown: (sessionData: SessionSnapshot) => Promise<void>;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Diagnostics panels barrel — re-exports all panel data provider classes.
+ *
+ * Import from this module to access the individual diagnostic panel providers.
+ */
+export { ToolCallsPanel } from '@/runtime/index.ts';
+export { AgentsPanel } from '@/runtime/index.ts';
+export { TasksPanel } from '@/runtime/index.ts';
+export { EventsPanel } from '@/runtime/index.ts';
+export { StateInspectorPanel } from '@/runtime/index.ts';
+export type { InspectableDomain } from '@/runtime/index.ts';
+export { HealthPanel } from '@/runtime/index.ts';
+export { DivergencePanel } from '@/runtime/index.ts';
+export { ReplayPanel } from '@/runtime/index.ts';
+export { PolicyPanel } from './policy.ts';
+export type { PolicyPanelSnapshot } from './policy.ts';
+export { ToolContractsPanel } from '@/runtime/index.ts';
+export { TransportPanel } from '@/runtime/index.ts';
+export type { TransportPanelSnapshot } from '@/runtime/index.ts';
+export { OpsPanel } from './ops.ts';
+export type { OpsAuditEntry } from './ops.ts';
+export { PanelResourcesPanel } from './panel-resources.ts';
+export { SecurityPanel } from '@/runtime/index.ts';
+export type { SecurityPanelSnapshot } from '@/runtime/index.ts';

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

@@ -0,0 +1,156 @@
+/**
+ * OpsPanel — diagnostic data provider for the Operator Control Plane.
+ *
+ * Subscribes to OPS_AUDIT events from the UI-facing ops event feed and maintains a
+ * bounded buffer of intervention records for display
+ * in the Ops panel.
+ *
+ * Controls are only shown when the OpsControlPlane reports the action is legal
+ * (state machine allows it), satisfying requirement: "No illegal action appears in UI".
+ */
+import type { RuntimeEventEnvelope } from '@/runtime/index.ts';
+import type { PanelConfig } from '@/runtime/index.ts';
+import { DEFAULT_PANEL_CONFIG, appendBounded, applyFilter } from '@/runtime/index.ts';
+import type { DiagnosticFilter } from '@/runtime/index.ts';
+import type { OpsInterventionReason, OpsEvent } from '@/runtime/index.ts';
+import type { UiEventFeed } from '../../ui-events.ts';
+
+// ---------------------------------------------------------------------------
+// Audit entry
+// ---------------------------------------------------------------------------
+
+/**
+ * Immutable audit record for a single operator intervention.
+ */
+export interface OpsAuditEntry {
+  /** Monotonic sequence number. */
+  readonly seq: number;
+  /** Epoch ms when the intervention was recorded. */
+  readonly ts: number;
+  /** The action taken (e.g. 'task.cancel', 'agent.cancel'). */
+  readonly action: string;
+  /** The target task or agent ID. */
+  readonly targetId: string;
+  /** Whether this intervention targeted a task or an agent. */
+  readonly targetKind: 'task' | 'agent';
+  /** The reason code for the intervention. */
+  readonly reason: OpsInterventionReason;
+  /** Optional operator note. */
+  readonly note?: string;
+  /** Outcome of the intervention. */
+  readonly outcome: 'success' | 'rejected' | 'error';
+  /** Error message if outcome is not success. */
+  readonly errorMessage?: string;
+  /** Trace identifier from the event envelope. */
+  readonly traceId: string;
+  /** Session identifier from the event envelope. */
+  readonly sessionId: string;
+}
+
+// ---------------------------------------------------------------------------
+// OpsPanel
+// ---------------------------------------------------------------------------
+
+/** Internal mutable record (same shape as immutable OpsAuditEntry). */
+type MutableAuditRecord = {
+  seq: number;
+  ts: number;
+  action: string;
+  targetId: string;
+  targetKind: 'task' | 'agent';
+  reason: OpsInterventionReason;
+  note?: string;
+  outcome: 'success' | 'rejected' | 'error';
+  errorMessage?: string;
+  traceId: string;
+  sessionId: string;
+};
+
+/** Type alias for the OPS_AUDIT event shape. */
+type OpsAuditEvent = Extract<OpsEvent, { type: 'OPS_AUDIT' }>;
+
+export class OpsPanel {
+  private readonly _config: PanelConfig;
+  private readonly _events: UiEventFeed<OpsEvent>;
+
+  private readonly _audit: MutableAuditRecord[] = [];
+  private _seq = 0;
+
+  private readonly _subscribers = new Set<() => void>();
+  private _unsub: (() => void) | null = null;
+
+  public constructor(
+    events: UiEventFeed<OpsEvent>,
+    config: PanelConfig = DEFAULT_PANEL_CONFIG
+  ) {
+    this._config = config;
+    this._events = events;
+    this._start();
+  }
+
+  private _start(): void {
+    this._unsub = this._events.onEnvelope('OPS_AUDIT', (envelope) => {
+      this._handleAudit(envelope as RuntimeEventEnvelope<'OPS_AUDIT', OpsAuditEvent>);
+    });
+  }
+
+  private _handleAudit(
+    envelope: RuntimeEventEnvelope<'OPS_AUDIT', OpsAuditEvent>
+  ): void {
+    const payload = envelope.payload;
+
+    const record: MutableAuditRecord = {
+      seq: ++this._seq,
+      ts: envelope.ts,
+      action: payload.action,
+      targetId: payload.targetId,
+      targetKind: payload.targetKind,
+      reason: payload.reason,
+      note: payload.note,
+      outcome: payload.outcome,
+      errorMessage: payload.errorMessage,
+      traceId: envelope.traceId ?? '',
+      sessionId: envelope.sessionId ?? '',
+    };
+
+    appendBounded(this._audit, record, this._config.bufferLimit);
+    this._notify();
+  }
+
+  /**
+   * Returns a filtered snapshot of the audit log, most recent first.
+   */
+  public getSnapshot(filter?: DiagnosticFilter): OpsAuditEntry[] {
+    const entries = this._audit.map((r) => ({ ...r }) as OpsAuditEntry);
+    return applyFilter(entries, filter, (e) => e.ts);
+  }
+
+  /**
+   * Subscribe to data changes. Returns an unsubscribe function.
+   */
+  public subscribe(callback: () => void): () => void {
+    this._subscribers.add(callback);
+    return () => { this._subscribers.delete(callback); };
+  }
+
+  /**
+   * Dispose the panel, unsubscribing from the event bus.
+   */
+  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 panel
+      }
+    }
+  }
+}