@pellux/goodvibes-tui 0.18.4

package/src/panels/builtin/shared.ts

@@ -0,0 +1,240 @@
+import type { ConfigManager } from '../../config/manager.ts';
+import type { ServiceRegistry } from '../../config/service-registry.ts';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools/registry';
+import type { ProviderRegistry } from '../../providers/registry.ts';
+import type { Orchestrator } from '../../core/orchestrator.ts';
+import type { MemoryRegistry } from '../../state/memory-store.ts';
+import type { ApprovalBroker, SharedSessionBroker } from '../../control-plane/index.ts';
+import type { AutomationManager } from '../../automation/index.ts';
+import type { ControlPlaneRecentEvent } from '../../control-plane/gateway.ts';
+import type { UiRuntimeServices } from '../../runtime/ui-services.ts';
+import type { PluginManagerObserver } from '../../plugins/manager.ts';
+import type { HookWorkbench } from '../../hooks/workbench.ts';
+import type { HookDispatcher } from '../../hooks/dispatcher.ts';
+import type { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+import type { McpRegistry } from '../../mcp/registry.ts';
+import type { PolicyRuntimeState } from '../../runtime/permissions/policy-runtime.ts';
+import type { SessionManager } from '../../sessions/manager.ts';
+import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
+import type { UserAuthManager } from '@pellux/goodvibes-sdk/platform/security/user-auth';
+import type { SessionMemoryStore } from '@pellux/goodvibes-sdk/platform/core/session-memory';
+import type { ExecutionPlanManager } from '@pellux/goodvibes-sdk/platform/core/execution-plan';
+import type { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core/adaptive-planner';
+import type { ApiTokenAuditor } from '@pellux/goodvibes-sdk/platform/security/token-audit';
+import type { PanelHealthMonitor } from '@pellux/goodvibes-sdk/platform/runtime/perf/panel-health-monitor';
+import type { WorktreeRegistry } from '../../runtime/worktree/registry.ts';
+import type { SandboxSessionRegistry } from '../../runtime/sandbox/session-registry.ts';
+
+export interface BuiltinPanelDeps {
+  /** Config manager for settings-sync and other config-backed panels. */
+  configManager?: ConfigManager;
+  /** Getter returning the main orchestrator's cumulative token usage. */
+  getOrchestratorUsage?: () => { input: number; output: number; cacheRead: number; cacheWrite: number; model?: string };
+  /** Optional cost budget alert threshold in USD (0 = disabled). */
+  budgetThreshold?: number;
+  /** Tool registry for Docs panel. */
+  toolRegistry?: ToolRegistry;
+  /** Provider registry for Docs panel model list. */
+  providerRegistry: ProviderRegistry;
+  /** Local auth manager for panels that inspect shared auth state. */
+  localUserAuthManager?: UserAuthManager;
+  /** Session manager for panels that inspect shared session state. */
+  sessionManager?: SessionManager;
+  /** Subscription manager for panels that inspect shared provider subscription state. */
+  subscriptionManager?: SubscriptionManager;
+  /** Shared service registry for services-backed panels. */
+  serviceRegistry?: ServiceRegistry;
+  /** Context window size in tokens (for ContextVisualizerPanel). */
+  contextWindow?: number;
+  /** Main Orchestrator instance for TokenBudgetPanel.wire(). */
+  orchestrator?: Orchestrator;
+  /** Callback returning the current model context window size (for TokenBudgetPanel). */
+  getCtxWindow?: () => number;
+  /** Resume a saved session directly through the session controller path. */
+  resumeSession?: (sessionId: string) => void;
+  /** Request a shell repaint directly rather than routing through a retired event path. */
+  requestRender?: () => void;
+  /** ForensicsRegistry for the Forensics panel. */
+  forensicsRegistry?: import('@pellux/goodvibes-sdk/platform/runtime/forensics/registry').ForensicsRegistry;
+  /** EvalRegistry for the Eval panel. */
+  evalRegistry?: import('../eval-panel.ts').EvalRegistry;
+  /** MemoryRegistry for the Memory panel. */
+  memoryRegistry?: MemoryRegistry;
+  /** Shared policy runtime state for governance/policy diagnostics. */
+  policyRuntimeState?: import('../../runtime/permissions/policy-runtime.ts').PolicyRuntimeState;
+  /** Approval broker for control-plane/operator panels. */
+  approvalBroker?: ApprovalBroker;
+  /** Shared session broker for control-plane/operator panels. */
+  sessionBroker?: SharedSessionBroker;
+  /** Automation manager for schedule/operator panels. */
+  automationManager?: AutomationManager;
+  /** Recent control-plane events provider for control-plane/operator panels. */
+  getControlPlaneRecentEvents?: (limit: number) => readonly ControlPlaneRecentEvent[];
+  /** Token auditor for the security control-room panel. */
+  tokenAuditor: ApiTokenAuditor;
+  /** Shared panel-health monitor for rate-limited panels and diagnostics. */
+  panelHealthMonitor: PanelHealthMonitor;
+  /** Shared worktree registry for worktree surfaces. */
+  worktreeRegistry: WorktreeRegistry;
+  /** Shared sandbox session registry for sandbox surfaces and tools. */
+  sandboxSessionRegistry: SandboxSessionRegistry;
+  /** Session memory store for context and token budget panels. */
+  sessionMemoryStore?: SessionMemoryStore;
+  /** Execution plan manager for plan dashboard panels. */
+  planManager?: ExecutionPlanManager;
+  /** Adaptive planner for ops strategy panels. */
+  adaptivePlanner?: AdaptivePlanner;
+  /** Shared system-messages panel instance attached from boot so low-priority chatter stays out of conversation. */
+  systemMessagesPanel?: import('../system-messages-panel.ts').SystemMessagesPanel;
+  /** Explicit UI-facing runtime services for agent/process/WRFC/remote panels and modals. */
+  uiServices?: UiRuntimeServices;
+  /** Shared plugin manager observer for plugin and security panels. */
+  pluginManager?: PluginManagerObserver;
+  /** Shared hook dispatcher for the hooks control-room panel. */
+  hookDispatcher?: Pick<HookDispatcher, 'listHooks' | 'getChains'>;
+  /** Shared hook workbench for the hooks control-room panel. */
+  hookWorkbench?: HookWorkbench;
+  /** Shared hook activity tracker for the hooks control-room panel. */
+  hookActivityTracker?: Pick<HookActivityTracker, 'listRecent'>;
+  /** Shared MCP registry for MCP/security control-room panels. */
+  mcpRegistry?: McpRegistry;
+}
+
+export type ResolvedBuiltinPanelDeps = Omit<
+  BuiltinPanelDeps,
+  | 'configManager'
+  | 'localUserAuthManager'
+  | 'sessionManager'
+  | 'subscriptionManager'
+  | 'serviceRegistry'
+  | 'sessionMemoryStore'
+  | 'planManager'
+  | 'adaptivePlanner'
+  | 'policyRuntimeState'
+  | 'systemMessagesPanel'
+> & {
+  readonly configManager: ConfigManager;
+  readonly localUserAuthManager: UserAuthManager;
+  readonly sessionManager: SessionManager;
+  readonly subscriptionManager: SubscriptionManager;
+  readonly serviceRegistry: ServiceRegistry;
+  readonly sessionMemoryStore: SessionMemoryStore;
+  readonly planManager: ExecutionPlanManager;
+  readonly adaptivePlanner: AdaptivePlanner;
+  readonly policyRuntimeState: PolicyRuntimeState;
+  readonly systemMessagesPanel: import('../system-messages-panel.ts').SystemMessagesPanel;
+};
+
+export interface ControlPlanePanelFactoryDeps {
+  readonly approvalBroker: ApprovalBroker;
+  readonly sessionBroker: SharedSessionBroker;
+  readonly getControlPlaneRecentEvents: (limit: number) => readonly ControlPlaneRecentEvent[];
+}
+
+function requireBuiltinPanelDep<TValue>(value: TValue | undefined, message: string): TValue {
+  if (value === undefined) {
+    throw new Error(message);
+  }
+  return value;
+}
+
+export function resolveBuiltinPanelDeps(deps: BuiltinPanelDeps): ResolvedBuiltinPanelDeps {
+  const uiServices = requireUiServices(deps);
+  return {
+    ...deps,
+    configManager: requireBuiltinPanelDep(
+      uiServices.platform.configManager,
+      'Config manager must be wired at bootstrap for builtin panels.',
+    ),
+    localUserAuthManager: requireBuiltinPanelDep(
+      uiServices.platform.localUserAuthManager,
+      'Local auth manager must be wired at bootstrap for builtin panels.',
+    ),
+    sessionManager: requireBuiltinPanelDep(
+      uiServices.sessions.sessionManager,
+      'Session manager must be wired at bootstrap for builtin panels.',
+    ),
+    subscriptionManager: requireBuiltinPanelDep(
+      uiServices.platform.subscriptionManager,
+      'Subscription manager must be wired at bootstrap for builtin panels.',
+    ),
+    serviceRegistry: requireBuiltinPanelDep(
+      uiServices.platform.serviceRegistry,
+      'Service registry must be wired at bootstrap for builtin panels.',
+    ),
+    sessionMemoryStore: requireBuiltinPanelDep(
+      uiServices.sessions.sessionMemoryStore,
+      'Session memory store must be wired at bootstrap for builtin panels.',
+    ),
+    planManager: requireBuiltinPanelDep(
+      uiServices.planning.planManager,
+      'Execution plan manager must be wired at bootstrap for builtin panels.',
+    ),
+    adaptivePlanner: requireBuiltinPanelDep(
+      uiServices.planning.adaptivePlanner,
+      'Adaptive planner must be wired at bootstrap for builtin panels.',
+    ),
+    policyRuntimeState: requireBuiltinPanelDep(
+      uiServices.platform.policyRuntimeState,
+      'Policy runtime state must be wired at bootstrap for builtin panels.',
+    ),
+    systemMessagesPanel: requireBuiltinPanelDep(
+      deps.systemMessagesPanel,
+      'System messages panel must be wired at bootstrap for builtin panels.',
+    ),
+  };
+}
+
+export function requireControlPlanePanelDeps(deps: BuiltinPanelDeps): ControlPlanePanelFactoryDeps {
+  if (!deps.approvalBroker || !deps.sessionBroker || !deps.getControlPlaneRecentEvents) {
+    throw new Error('ControlPlanePanel requires approval/session brokers and recent-event access to be wired at bootstrap.');
+  }
+  return {
+    approvalBroker: deps.approvalBroker,
+    sessionBroker: deps.sessionBroker,
+    getControlPlaneRecentEvents: deps.getControlPlaneRecentEvents,
+  };
+}
+
+export function requireAutomationManager(deps: BuiltinPanelDeps): AutomationManager {
+  if (!deps.automationManager) {
+    throw new Error('SchedulePanel requires an automation manager to be wired at bootstrap.');
+  }
+  return deps.automationManager;
+}
+
+export function requireUiServices(deps: BuiltinPanelDeps): UiRuntimeServices {
+  if (!deps.uiServices) {
+    throw new Error('UI runtime services must be wired at bootstrap for agent, process, WRFC, and remote panels.');
+  }
+  return deps.uiServices;
+}
+
+export function requirePluginManager(deps: BuiltinPanelDeps): PluginManagerObserver {
+  if (!deps.pluginManager) {
+    throw new Error('Plugin manager must be wired at bootstrap for plugin and security panels.');
+  }
+  return deps.pluginManager;
+}
+
+export function requireHookPanelDeps(deps: BuiltinPanelDeps): {
+  readonly hookDispatcher: Pick<HookDispatcher, 'listHooks' | 'getChains'>;
+  readonly hookWorkbench: HookWorkbench;
+  readonly hookActivityTracker: Pick<HookActivityTracker, 'listRecent'>;
+} {
+  if (!deps.hookDispatcher || !deps.hookWorkbench || !deps.hookActivityTracker) {
+    throw new Error('Hook dispatcher, hook activity tracker, and hook workbench must be wired at bootstrap for the hooks panel.');
+  }
+  return {
+    hookDispatcher: deps.hookDispatcher,
+    hookWorkbench: deps.hookWorkbench,
+    hookActivityTracker: deps.hookActivityTracker,
+  };
+}
+
+export function requireMcpRegistry(deps: BuiltinPanelDeps): McpRegistry {
+  if (!deps.mcpRegistry) {
+    throw new Error('MCP registry must be wired at bootstrap for MCP and security panels.');
+  }
+  return deps.mcpRegistry;
+}

package/src/panels/builtin-panels.ts

@@ -0,0 +1,23 @@
+import type { PanelManager } from './panel-manager.ts';
+import { resolveBuiltinPanelDeps, type BuiltinPanelDeps } from './builtin/shared.ts';
+import { registerDevelopmentPanels } from './builtin/development.ts';
+import { registerOperationsPanels } from './builtin/operations.ts';
+import { registerAgentPanels } from './builtin/agent.ts';
+import { registerSessionPanels } from './builtin/session.ts';
+import { registerKnowledgePanels } from './builtin/knowledge.ts';
+
+/**
+ * Register all built-in panel types with the given PanelManager.
+ *
+ * Call this once during application startup, before opening any panels.
+ */
+export function registerBuiltinPanels(manager: PanelManager, deps: BuiltinPanelDeps): void {
+  const resolved = resolveBuiltinPanelDeps(deps);
+  registerDevelopmentPanels(manager, resolved);
+  registerOperationsPanels(manager, resolved);
+  registerAgentPanels(manager, resolved);
+  registerSessionPanels(manager, resolved);
+  registerKnowledgePanels(manager, resolved);
+}
+
+export type { BuiltinPanelDeps } from './builtin/shared.ts';

package/src/panels/cockpit-panel.ts

@@ -0,0 +1,183 @@
+import type { Line } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { createEmptyLine } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { BasePanel } from './base-panel.ts';
+import type { UiCockpitSnapshot, UiReadModel } from '../runtime/ui-read-models.ts';
+import {
+  buildGuidanceLine,
+  buildKeyValueLine,
+  buildPanelLine,
+  buildPanelWorkspace,
+  buildStatPill,
+  DEFAULT_PANEL_PALETTE,
+  type PanelWorkspaceSection,
+} from './polish.ts';
+
+const C = {
+  ...DEFAULT_PANEL_PALETTE,
+  header: '#cbd5e1',
+  headerBg: '#0f172a',
+} as const;
+
+function pickColor(value: number, warnAt = 1, badAt = 3): string {
+  if (value >= badAt) return C.bad;
+  if (value >= warnAt) return C.warn;
+  return C.good;
+}
+
+const WORKSPACE_IDS = ['flow', 'governance', 'health', 'domains'] as const;
+
+export class CockpitPanel extends BasePanel {
+  private readonly unsub: (() => void) | null;
+  private selectedWorkspaceIndex = 0;
+
+  public constructor(private readonly readModel?: UiReadModel<UiCockpitSnapshot>) {
+    super('cockpit', 'Cockpit', 'O', 'monitoring');
+    this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
+  }
+
+  public override onDestroy(): void {
+    this.unsub?.();
+  }
+
+  public handleInput(key: string): boolean {
+    if (key === 'left' || key === 'h') {
+      this.selectedWorkspaceIndex = Math.max(0, this.selectedWorkspaceIndex - 1);
+      this.markDirty();
+      return true;
+    }
+    if (key === 'right' || key === 'l') {
+      this.selectedWorkspaceIndex = Math.min(WORKSPACE_IDS.length - 1, this.selectedWorkspaceIndex + 1);
+      this.markDirty();
+      return true;
+    }
+    if (key === 'home') {
+      this.selectedWorkspaceIndex = 0;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'end') {
+      this.selectedWorkspaceIndex = WORKSPACE_IDS.length - 1;
+      this.markDirty();
+      return true;
+    }
+    return false;
+  }
+
+  public render(width: number, height: number): Line[] {
+    this.needsRender = false;
+
+    if (!this.readModel) {
+      const lines: Line[] = [buildPanelLine(width, [[' Runtime read model not wired into this panel yet.', C.empty]])];
+      const workspace = buildPanelWorkspace(width, height, {
+        title: 'Operator Cockpit',
+        sections: [{ lines }],
+        palette: C,
+      });
+      while (workspace.length < height) workspace.push(createEmptyLine(width));
+      return workspace;
+    }
+
+    const snapshot = this.readModel.getSnapshot();
+    const selectedWorkspace = WORKSPACE_IDS[this.selectedWorkspaceIndex] ?? 'flow';
+
+    const flowLines: Line[] = [
+      buildPanelLine(width, [
+        ...buildStatPill('graphs', String(snapshot.activeGraphs), C.label, pickColor(snapshot.activeGraphs, 1, 4)),
+        ...buildStatPill('running', String(snapshot.runningTasks), C.label, C.value),
+        ...buildStatPill('blocked', String(snapshot.blockedTasks), C.label, pickColor(snapshot.blockedTasks)),
+        ...buildStatPill('failed', String(snapshot.failedTasks), C.label, pickColor(snapshot.failedTasks)),
+        ...buildStatPill('guards', String(snapshot.guardTrips), C.label, pickColor(snapshot.guardTrips)),
+      ]),
+      buildPanelLine(width, [
+        ...buildStatPill('blocked comms', String(snapshot.blockedMessages), C.label, pickColor(snapshot.blockedMessages)),
+        ...buildStatPill('pending approvals', String(snapshot.pendingPermissions), C.label, pickColor(snapshot.pendingPermissions)),
+        ...buildStatPill('denied', String(snapshot.deniedPermissions), C.label, pickColor(snapshot.deniedPermissions)),
+      ]),
+    ];
+    const governanceLines: Line[] = [
+      buildPanelLine(width, [
+        ...buildStatPill('preflight', snapshot.preflightStatus.toUpperCase(), C.label, snapshot.preflightStatus === 'block' ? C.bad : snapshot.preflightStatus === 'warn' ? C.warn : snapshot.preflightStatus === 'pass' ? C.good : C.dim),
+        ...buildStatPill('issues', String(snapshot.preflightIssueCount), C.label, pickColor(snapshot.preflightIssueCount)),
+        ...buildStatPill('lint', String(snapshot.lintFindingCount), C.label, pickColor(snapshot.lintFindingCount)),
+        ...buildStatPill('allow-all MCP', String(snapshot.elevatedMcp), C.label, pickColor(snapshot.elevatedMcp)),
+        ...buildStatPill('unhealthy MCP', String(snapshot.unhealthyMcp), C.label, pickColor(snapshot.unhealthyMcp)),
+      ]),
+      buildPanelLine(width, [
+        ...buildStatPill('token blocked', String(snapshot.tokenBlockedCount), C.label, pickColor(snapshot.tokenBlockedCount)),
+        ...buildStatPill('overdue', String(snapshot.tokenRotationOverdueCount), C.label, pickColor(snapshot.tokenRotationOverdueCount)),
+        ...buildStatPill('scope violations', String(snapshot.tokenScopeViolationCount), C.label, pickColor(snapshot.tokenScopeViolationCount)),
+        ...buildStatPill('warnings', String(snapshot.tokenRotationWarningCount), C.label, pickColor(snapshot.tokenRotationWarningCount)),
+      ]),
+    ];
+    const healthLines: Line[] = [
+      buildPanelLine(width, [
+        ...buildStatPill('incidents', String(snapshot.incidentCount), C.label, pickColor(snapshot.incidentCount)),
+        ...buildStatPill('plugins', String(snapshot.erroredPlugins), C.label, pickColor(snapshot.erroredPlugins)),
+        ...buildStatPill('integrations', String(snapshot.failingIntegrations), C.label, pickColor(snapshot.failingIntegrations)),
+      ]),
+    ];
+    if (snapshot.latestIncident) {
+      healthLines.push(buildPanelLine(width, [
+        [' latest incident ', C.label],
+        [snapshot.latestIncident.classification, C.bad],
+        ['  ', C.label],
+        [snapshot.latestIncident.summary.slice(0, Math.max(0, width - 19 - snapshot.latestIncident.classification.length)), C.dim],
+      ]));
+    }
+    const domainLines: Line[] = [buildPanelLine(width, [[
+      `tasks:${snapshot.taskCount} agents:${snapshot.agentCount} graphs:${snapshot.totalGraphs} comms:${snapshot.communicationCount} mcp:${snapshot.mcpServerCount} plugins:${snapshot.pluginCount}`,
+      C.dim,
+    ]])];
+    const workspaceLines: Line[] = [];
+    if (selectedWorkspace === 'flow') {
+      workspaceLines.push(buildKeyValueLine(width, [
+        { label: 'running', value: String(snapshot.runningTasks), valueColor: C.value },
+        { label: 'blocked', value: String(snapshot.blockedTasks), valueColor: pickColor(snapshot.blockedTasks) },
+        { label: 'graphs', value: String(snapshot.activeGraphs), valueColor: pickColor(snapshot.activeGraphs, 1, 4) },
+      ], C));
+      workspaceLines.push(buildGuidanceLine(width, '/orchestration', 'inspect graph state, retries, and subtree controls', C));
+      workspaceLines.push(buildGuidanceLine(width, '/tasks', 'review active task pressure and task-specific output', C));
+    } else if (selectedWorkspace === 'governance') {
+      workspaceLines.push(buildKeyValueLine(width, [
+        { label: 'preflight', value: snapshot.preflightStatus.toUpperCase(), valueColor: snapshot.preflightStatus === 'block' ? C.bad : snapshot.preflightStatus === 'warn' ? C.warn : snapshot.preflightStatus === 'pass' ? C.good : C.dim },
+        { label: 'lint', value: String(snapshot.lintFindingCount), valueColor: pickColor(snapshot.lintFindingCount) },
+        { label: 'allow-all mcp', value: String(snapshot.elevatedMcp), valueColor: pickColor(snapshot.elevatedMcp) },
+      ], C));
+      workspaceLines.push(buildGuidanceLine(width, '/policy', 'run simulation, preflight, and bundle review', C));
+      workspaceLines.push(buildGuidanceLine(width, '/security', 'inspect trust, tokens, quarantines, and incident pressure', C));
+    } else if (selectedWorkspace === 'health') {
+      workspaceLines.push(buildKeyValueLine(width, [
+        { label: 'incidents', value: String(snapshot.incidentCount), valueColor: pickColor(snapshot.incidentCount) },
+        { label: 'plugins', value: String(snapshot.erroredPlugins), valueColor: pickColor(snapshot.erroredPlugins) },
+        { label: 'integrations', value: String(snapshot.failingIntegrations), valueColor: pickColor(snapshot.failingIntegrations) },
+      ], C));
+      workspaceLines.push(buildGuidanceLine(width, '/incident latest', 'inspect the latest incident bundle and replay fallout', C));
+      workspaceLines.push(buildGuidanceLine(width, '/plugins', 'review errored plugins and provenance posture', C));
+    } else {
+      workspaceLines.push(buildKeyValueLine(width, [
+        { label: 'tasks', value: String(snapshot.taskCount), valueColor: C.value },
+        { label: 'comms', value: String(snapshot.communicationCount), valueColor: C.value },
+        { label: 'mcp', value: String(snapshot.mcpServerCount), valueColor: C.value },
+      ], C));
+      workspaceLines.push(buildGuidanceLine(width, '/mcp', 'inspect trust, quarantine, and risky server posture', C));
+      workspaceLines.push(buildGuidanceLine(width, '/communication', 'review blocked lanes and agent message flow', C));
+    }
+
+    const sections: PanelWorkspaceSection[] = [
+      { title: 'Flow', lines: flowLines },
+      { title: 'Governance', lines: governanceLines },
+      { title: 'Health', lines: healthLines },
+      { title: 'Domains', lines: domainLines },
+      { title: 'Selected Workspace', lines: workspaceLines },
+    ];
+    const lines = buildPanelWorkspace(width, height, {
+      title: 'Operator Cockpit',
+      intro: 'Live runtime pressure across orchestration, approvals, governance, integrations, and provider trust posture.',
+      sections,
+      footerLines: [buildPanelLine(width, [[`  Left/Right move workspace focus  Home/End jump  focus=${selectedWorkspace}`, C.dim]])],
+      palette: C,
+    });
+    while (lines.length < height) lines.push(createEmptyLine(width));
+    return lines.slice(0, height);
+  }
+}

package/src/panels/communication-panel.ts

@@ -0,0 +1,191 @@
+import type { Line } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { createEmptyLine } from '@pellux/goodvibes-sdk/platform/types/grid';
+import { BasePanel } from './base-panel.ts';
+import type { UiCommunicationSnapshot, UiReadModel } from '../runtime/ui-read-models.ts';
+import { truncateDisplay } from '@pellux/goodvibes-sdk/platform/utils/terminal-width';
+import {
+  buildBodyText,
+  buildEmptyState,
+  buildGuidanceLine,
+  buildKeyValueLine,
+  buildPanelLine,
+  buildPanelWorkspace,
+  DEFAULT_PANEL_PALETTE,
+  resolvePrimaryScrollableSection,
+  type PanelWorkspaceSection,
+} from './polish.ts';
+import { getTrackedVisibleWindow } from '../renderer/surface-layout.ts';
+
+const C = {
+  ...DEFAULT_PANEL_PALETTE,
+  header: '#94a3b8',
+  headerBg: '#1e293b',
+  ok: '#22c55e',
+  warn: '#eab308',
+  error: '#ef4444',
+  selectBg: '#0f172a',
+} as const;
+
+export class CommunicationPanel extends BasePanel {
+  private readonly readModel?: UiReadModel<UiCommunicationSnapshot>;
+  private readonly unsub: (() => void) | null;
+  private selectedIndex = 0;
+  private scrollOffset = 0;
+
+  public constructor(readModel?: UiReadModel<UiCommunicationSnapshot>) {
+    super('communication', 'Communication', 'Y', 'monitoring');
+    this.readModel = readModel;
+    this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
+  }
+
+  public override onDestroy(): void {
+    this.unsub?.();
+  }
+
+  public handleInput(key: string): boolean {
+    const records = this.records();
+    if (records.length === 0) return false;
+    if (key === 'up' || key === 'k') {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      this.markDirty();
+      return true;
+    }
+    if (key === 'down' || key === 'j') {
+      this.selectedIndex = Math.min(records.length - 1, this.selectedIndex + 1);
+      this.markDirty();
+      return true;
+    }
+    return false;
+  }
+
+  private records() {
+    if (!this.readModel) return [];
+    return [...this.readModel.getSnapshot().records];
+  }
+
+  public render(width: number, height: number): Line[] {
+    this.needsRender = false;
+    const intro = 'Structured agent communication, routing policy outcomes, and delivery status across orchestration trees.';
+    const footerLines = [buildPanelLine(width, [['  Up/Down move through messages', C.dim]])];
+
+    if (!this.readModel) {
+      const workspace = buildPanelWorkspace(width, height, {
+        title: 'Communication Control Room',
+        intro,
+        sections: [{
+          lines: buildEmptyState(
+            width,
+            ' Runtime store not wired into this panel yet.',
+            'This workspace needs the live runtime store before it can show communication history and policy outcomes.',
+            [{ command: '/communication', summary: 'reopen the workspace from the shell-owned runtime' }],
+            C,
+          ),
+        }],
+        palette: C,
+      });
+      while (workspace.length < height) workspace.push(createEmptyLine(width));
+      return workspace;
+    }
+
+    const snapshot = this.readModel.getSnapshot();
+    const records = this.records();
+
+    if (records.length === 0) {
+      const workspace = buildPanelWorkspace(width, height, {
+        title: 'Communication Control Room',
+        intro,
+        sections: [{
+          title: 'Communication posture',
+          lines: [
+            buildKeyValueLine(width, [
+              { label: 'sent', value: String(snapshot.totalSent), valueColor: snapshot.totalSent > 0 ? C.info : C.dim },
+              { label: 'delivered', value: String(snapshot.totalDelivered), valueColor: snapshot.totalDelivered > 0 ? C.ok : C.dim },
+              { label: 'blocked', value: String(snapshot.totalBlocked), valueColor: snapshot.totalBlocked > 0 ? C.error : C.dim },
+            ], C),
+            buildGuidanceLine(width, '/communication', 'review structured message flow, delivery posture, and blocked routing decisions', C),
+            ...buildEmptyState(
+              width,
+              ' No structured communication recorded yet.',
+              'Messages, escalations, findings, and handoffs will appear here once orchestration starts routing them through the communication policy.',
+              [
+                { command: '/orchestration', summary: 'review graphs and recursive agent activity' },
+                { command: '/communication', summary: 'reopen this workspace once the runtime emits message traffic' },
+              ],
+              C,
+            ),
+          ],
+        }],
+        palette: C,
+      });
+      while (workspace.length < height) workspace.push(createEmptyLine(width));
+      return workspace;
+    }
+
+    this.selectedIndex = Math.min(this.selectedIndex, records.length - 1);
+    const postureLines: Line[] = [
+      buildKeyValueLine(width, [
+        { label: 'sent', value: String(snapshot.totalSent), valueColor: snapshot.totalSent > 0 ? C.info : C.dim },
+        { label: 'delivered', value: String(snapshot.totalDelivered), valueColor: snapshot.totalDelivered > 0 ? C.ok : C.dim },
+        { label: 'blocked', value: String(snapshot.totalBlocked), valueColor: snapshot.totalBlocked > 0 ? C.error : C.dim },
+        { label: 'selected', value: `${records[this.selectedIndex]?.fromId ?? 'n/a'} -> ${records[this.selectedIndex]?.toId ?? 'n/a'}`, valueColor: C.value },
+      ], C),
+      buildGuidanceLine(width, '/orchestration', 'inspect recursive routing, message handoff, and blocked broadcast posture', C),
+    ];
+
+    const selected = records[this.selectedIndex]!;
+    const detailLines: Line[] = [
+      buildPanelLine(width, [['  Route: ', C.label], [`${selected.scope} / ${selected.kind}`, C.value], ['  Status: ', C.label], [selected.status, selected.status === 'blocked' ? C.error : C.ok]]),
+      buildPanelLine(width, [['  From: ', C.label], [selected.fromId, C.value], ['  To: ', C.label], [selected.toId, C.value]]),
+      buildPanelLine(width, [['  Roles: ', C.label], [`${selected.fromRole ?? 'unknown'} -> ${selected.toRole ?? 'unknown'}`, C.dim]]),
+    ];
+    if (selected.reason) {
+      detailLines.push(buildPanelLine(width, [['  Reason: ', C.label], [truncateDisplay(selected.reason, Math.max(0, width - 11)), C.warn]]));
+    }
+    detailLines.push(...buildBodyText(width, ` Content: ${selected.content}`, C));
+    const postureSection: PanelWorkspaceSection = { title: 'Communication posture', lines: postureLines };
+    const detailSection: PanelWorkspaceSection = { title: 'Selected Message', lines: detailLines };
+    const rawOverviewLines: Line[] = records.map((record, absolute) => {
+      const bg = absolute === this.selectedIndex ? C.selectBg : undefined;
+      const color = record.status === 'blocked' ? C.error : record.status === 'delivered' ? C.ok : C.info;
+      return buildPanelLine(width, [
+        [' ', C.label, bg],
+        [record.status.padEnd(10), color, bg],
+        [` ${record.kind.padEnd(10)}`, C.info, bg],
+        [` ${truncateDisplay(`${record.fromId} -> ${record.toId}`, 28).padEnd(28)}`, C.value, bg],
+        [` ${truncateDisplay(record.content, Math.max(0, width - 53))}`, C.dim, bg],
+      ]);
+    });
+    const resolvedMessagesSection = resolvePrimaryScrollableSection(width, height, {
+      intro,
+      footerLines,
+      palette: C,
+      beforeSections: [postureSection],
+      section: {
+        title: 'Recent Messages',
+        scrollableLines: rawOverviewLines,
+        selectedIndex: this.selectedIndex,
+        scrollOffset: this.scrollOffset,
+        guardRows: 1,
+        minRows: 4,
+        appendWindowSummary: { dimColor: C.dim },
+      },
+      afterSections: [detailSection],
+    });
+    this.scrollOffset = resolvedMessagesSection.scrollOffset;
+
+    const sections: PanelWorkspaceSection[] = [
+      postureSection,
+      resolvedMessagesSection.section,
+      detailSection,
+    ];
+    const lines = buildPanelWorkspace(width, height, {
+      title: 'Communication Control Room',
+      intro,
+      sections,
+      footerLines,
+      palette: C,
+    });
+    while (lines.length < height) lines.push(createEmptyLine(width));
+    return lines.slice(0, height);
+  }
+}