K8 GUI Layer

K8 is the human interface layer of WeftOS -- a web-based GUI that provides real-time visibility into kernel state and interactive administration. It is designed as a self-building, agent-extensible interface where the Weaver (and other authorized agents) can generate, improve, and distribute TypeScript-based applications that interact deeply with the Rust kernel.

Source: gui/ Stack: React 19, TypeScript, Vite, Tailwind CSS, Cytoscape.js Phase: K8

Design Philosophy

WeftOS is not just a kernel for agents and services -- it is a self-aware, self-extending operating system. The ECC cognitive substrate already ingests its own development history and uses it for self-improvement. The K8 GUI closes the loop: making the system visually inspectable, interactively manageable, and dynamically extensible by agents themselves.

Key principles:

• Agent-first extensibility: The Weaver (or any authorized agent) can generate, modify, and hot-reload user-facing applications without restarting the kernel or GUI.
• Heterogeneous awareness: The GUI gracefully degrades or requests missing data across the mesh (cloud, edge, browser, WASI, embedded). Partial views are acceptable -- the UI knows when to trigger ServiceApi calls for more data.
• Native binary feel with modern web power: Launch like a traditional OS executable while leveraging the TypeScript/React ecosystem for rapid UI development.
• 3D-first cognitive visualization: The ECC graph, service maps, mesh topology, deployment cycles, permission graphs, resource trees, HNSW clusters, impulses, and governance rules deserve spatial, interactive 3D representation.
• Governed and secure: Every GUI action routes through the existing ServiceApi, dual-layer GovernanceGate, and chain witnessing. No bypasses.
• Self-building: The OS GUI itself is introspectable and improvable by the ECC/Weaver loop. Agents can propose UI changes, new apps, and evolve the shell.

Current Implementation

Dashboard

Read-only overview of kernel state:

• Metrics grid: process count, chain height, uptime, message rates
• Process table: active agents with PID, state, CPU/memory
• Chain events: recent ExoChain commits with hash, type, timestamp
• Health indicators: service status badges

Admin Forms

Five CRUD forms testing the full TypeScript-to-Rust round-trip:

1. Spawn Agent -- name, capabilities, restart strategy
2. Stop Agent -- select by PID, graceful/force
3. Set Config -- namespace, key, value (typed)
4. Query Chain -- hash or height lookup
5. Register Service -- name, port, health endpoint

Knowledge Graph Visualization

Interactive causal graph visualization using Cytoscape.js:

• 8 edge type colors: Causes (red), Enables (green), Correlates (blue), etc.
• Node sizing: scales with degree (more connections = larger node)
• Community coloring: background tint by detected community
• Click-to-inspect: NodeDetail panel showing edges, metadata, community ID
• Search: highlight/dim filtering with search bar
• Coherence gauge: displays lambda_2 (algebraic connectivity)
• Layout: force-directed (cose) with configurable parameters

Architecture

+----------------+     WebSocket      +----------------+
|   React GUI    | <----------------> |  Kernel API    |
|  (Vite dev)    |     JSON messages  |  (Rust)        |
+----------------+                    +----------------+

TypeScript Types

TypeScript interfaces mirror Rust kernel structs:

• ProcessEntry, ProcessState, ResourceUsage
• ChainEvent, KernelMetrics
• CausalNode, CausalEdge, SpectralResult

WebSocket Hook

useKernelWebSocket hook manages the connection lifecycle:

• Auto-reconnect with exponential backoff
• Mock data mode for development (no kernel required)
• Message type routing to React state

Lego Block Architecture

The GUI uses a composable "Lego block" architecture where views and widgets are self-describing, independently loadable components. Each block is a standalone React component that declares its data requirements, layout preferences, and kernel service dependencies through a JSON descriptor.

Block Structure

A GUI block consists of:

1. JSON Descriptor -- declares the block's identity, data requirements, layout, and capabilities
2. React Component -- the TSX implementation
3. Service Bindings -- TypeScript types auto-generated from Rust kernel structs

Blocks can be nested, composed into dashboards, and distributed as governed app bundles.

JSON Descriptor Format

Each block is described by a JSON descriptor that the shell uses for layout, routing, and dependency resolution:

{
  "id": "process-explorer",
  "version": "1.0.0",
  "title": "Process Explorer",
  "description": "Interactive process table with state transitions",
  "category": "kernel",
  "icon": "cpu",
  "layout": {
    "minWidth": 400,
    "minHeight": 300,
    "defaultWidth": 800,
    "defaultHeight": 600,
    "resizable": true,
    "position": "center"
  },
  "data": {
    "services": ["kernel.process_table", "kernel.supervisor"],
    "subscriptions": ["process.state_change", "process.spawn", "process.stop"],
    "refreshInterval": 1000
  },
  "capabilities": {
    "required": ["kernel.ps", "kernel.inspect"],
    "optional": ["kernel.spawn", "kernel.stop"]
  },
  "governance": {
    "readOnly": false,
    "gateActions": ["agent.spawn", "agent.stop"]
  }
}

Key fields:

• data.services -- kernel services this block reads from. The shell ensures these services are available (locally or via mesh) before rendering.
• data.subscriptions -- WebSocket event topics for real-time updates.
• capabilities.required -- capabilities the current user/agent must have for the block to render. Missing capabilities hide the block.
• capabilities.optional -- capabilities that unlock additional features (e.g., write operations) when present.
• governance.gateActions -- actions that pass through the GovernanceGate before execution. The block's UI elements are automatically disabled when governance denies the action.

Dynamic Loading

Blocks can be loaded at runtime without rebuilding the shell:

1. Weaver generates a new TSX component + JSON descriptor
2. The bundle is signed and submitted for governance review
3. On approval, the block is registered in the shell's block registry
4. Users see the new block in the app launcher

This enables agents to extend the GUI without human intervention (subject to governance approval).

Console

The WeftOS console is a terminal-style interface embedded in the GUI that provides direct access to kernel commands:

• Command palette: fuzzy-search across all weave CLI commands
• Output rendering: structured JSON responses rendered as tables/trees
• History: command history persisted across sessions
• Auto-complete: tab completion from kernel service registry and process table
• Multi-pane: split view with console + live dashboard side by side

The console routes all commands through the same ServiceApi and governance pipeline as the graphical views. There is no privilege escalation through the console.

Tauri 2.0 Desktop Integration

The target desktop packaging uses Tauri 2.0 as the GUI host.

Why Tauri

• Produces tiny, secure, native-feeling binaries (few MB) using the OS's native WebView (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux).
• Full GPU acceleration in the WebView enables smooth 3D rendering.
• Backend remains pure Rust -- the GUI is just another client of the existing kernel abstractions (A2ARouter, ServiceApi, MeshAdapter, etc.).
• TypeScript integration with automatic bindings.
• Feature-gated (gui-tauri or similar) so edge/WASI/browser builds remain lightweight.
• Supports transparent windows, custom chrome, multi-window, system tray, and deep OS integration.

Rust-to-TypeScript Bridge

The bridge uses a combination of tools for zero-boilerplate type safety:

• tauri-bindgen or rspc (with Tauri adapter) -- defines a shared interface and auto-generates TypeScript declarations, invoke functions, and runtime validation.
• tauri-typegen or ts-rs -- scans #[tauri::command] functions and generates strongly-typed TS interfaces for all WeftOS types (ServiceEntry, ResolvedService, SyncStateDigest, ECC graph nodes/edges, PeerNode, governance rules, EffectVector scores, etc.).

This turns the kernel into a TypeScript app server: agents generate full TS applications that call into the mesh, ECC, chain, governance, and sensors as if they were local services.

3D Visualization

The GUI targets 3D-first visualization using React Three Fiber + Three.js:

ECC / Knowledge Graph Explorer

Spatial navigation of the causal Merkle vector graph:

• Nodes as 3D objects with force-directed layout
• Edge types (causal, crossref, impulse) with distinct colors and shapes
• Timestamps (HLC) and drill-down to chain events or resource tree subgraphs
• Weaver can generate new layouts or filters
• Performance via InstancedMesh for large graphs

Service and Mesh Topology Map

2D/3D graph of services, nodes (CloudNative, Edge, Browser, etc.), connections, and real-time status using NodeEccCapability and response scores.

Deployment and Task Cycles

Timeline views and graphs showing governance decisions, chain events, agent actions, and mesh propagations.

Asset and Resource Management

Browsable views of the ResourceTree with permissioning overlays and governance rule inspection.

Agent and Sensor Dashboard

Live views of running agents, impulses, HNSW queries, and sensor feeds. Partial data handling shows "available on remote node X" with one-click resolution.

Governance Console

Visual rule editor, genesis root verification, supersede flows with on-chain anchoring support.

Integration with Kernel Primitives

The GUI is not a separate layer -- it is a first-class client of the kernel:

• All interactions route through A2ARouter / ServiceApi (exactly like the MeshAdapter and RegistryQueryService).
• RegistryQueryService, CmvgSyncService, chain queries, tree diffs become directly callable from TypeScript.
• Mesh-aware: the UI can discover and invoke services on remote nodes. Partial data triggers "Request from peer" flows.
• Observability: response scores (RTT, success_rate, deny_rate, headroom, risk_delta) drive dynamic UI elements (node coloring, affinity-based recommendations, circuit-breaker visuals).
• Governance: every command passes the dual-layer GovernanceGate. UI actions are witnessed to the ExoChain.
• Cognitive sync: real-time updates via multiplexed QUIC streams (IPC + CMVG sync streams) feed live 3D graphs and dashboards.
• Self-awareness: the ECC graph includes the GUI codebase itself. Weaver can analyze, propose improvements, generate new components, and apply them.

Platform Support

Feature flags ensure the core kernel never depends on GUI crates.

Development

cd gui
npm install
npm run dev     # Vite dev server at localhost:5173
npm run build   # Production build (204KB JS, 17KB CSS)

Production build: 204KB JavaScript, 17KB CSS. No external CDN dependencies.

Block Engine (v0.2)

Sprint 12 introduced a production-ready Block Engine in gui/src/engine/ and gui/src/blocks/. The engine replaces the earlier prototype components with a fully recursive, registry-driven rendering system.

Core Engine (gui/src/engine/)

• BlockRegistry -- Central registry mapping block type strings to React components. Blocks self-register at import time. The registry supports dynamic registration for agent-generated blocks.
• BlockRenderer -- Recursive renderer that walks a block descriptor tree and instantiates the correct component for each node. Handles nesting (columns containing rows containing blocks) and error boundaries.
• StateStore -- Zustand-based state management with a Tauri bridge. Kernel state flows from Rust through Tauri commands into the Zustand store, and React components subscribe to slices. The store supports optimistic updates for responsive UI and rollback on kernel rejection.

Block Components (gui/src/blocks/)

10 composable block types ship out of the box:

Layout blocks (Column, Row, Grid, Tabs) accept child blocks, enabling arbitrarily deep nesting. A dashboard is a tree of blocks described by a JSON descriptor -- the BlockRenderer walks the tree and produces the final UI.

Example: Composing a Dashboard

{
  "type": "Grid",
  "props": { "columns": 2 },
  "children": [
    { "type": "Status", "props": { "service": "kernel.supervisor" } },
    { "type": "Status", "props": { "service": "kernel.mesh" } },
    {
      "type": "Tabs",
      "children": [
        { "type": "Table", "props": { "label": "Processes", "source": "kernel.ps" } },
        { "type": "Tree", "props": { "label": "Resources", "source": "kernel.tree" } }
      ]
    },
    { "type": "Terminal", "props": { "source": "kernel.logs" } }
  ]
}

Sprint 13 Additions

BudgetBlock (v0.3)

Source: gui/src/blocks/BudgetBlock.tsx

The BudgetBlock is a dashboard component that displays per-agent token usage, cost, and budget remaining. It reads from the StateStore key /kernel/metrics/cost (populated by KernelDataProvider) and renders:

• Total budget bar -- color-coded progress bar (green/amber/red) showing aggregate spend as a percentage of the total budget.
• Per-agent table -- sortable rows showing each agent's ID, tokens consumed, cost in USD, and remaining budget. Each row has a colored indicator dot reflecting budget utilisation.

Register the block by type name "Budget" in a dashboard descriptor:

{ "type": "Budget", "props": { "stateKey": "/kernel/metrics/cost" } }

The stateKey prop defaults to /kernel/metrics/cost and can be overridden to point at a different cost data source.

KernelDataProvider (v0.3)

Source: gui/src/engine/KernelDataProvider.tsx

The KernelDataProvider replaces the earlier mock-only data flow with a real Tauri bridge. It wraps the application tree and polls the kernel at a configurable interval (default 2 seconds) via four Tauri invoke calls:

Behavior modes:

• Tauri desktop -- polls the kernel and populates the Zustand StateStore. Connection state transitions through disconnected -> connecting -> connected. On error, an amber warning banner renders above the content.
• Browser / non-Tauri -- displays a "Connect to kernel" placeholder banner. Set allowMockFallback={true} to re-enable mock data in browser mode.

Usage:

<KernelDataProvider pollInterval={3000}>
  <App />
</KernelDataProvider>

ThemeSwitcher (v0.3)

Source: gui/src/components/ThemeSwitcher.tsx

A dropdown component for switching the active WeftOS theme at runtime. It integrates with the ThemeProvider context and persists the user's selection:

• Tauri desktop -- saves to kernel config via invoke('save_config', ...)
• Browser -- saves to localStorage under the key weftos-theme

The switcher lists all themes registered with registerTheme() and formats their names for display (e.g. ocean-dark becomes "Ocean Dark"). Drop it into any toolbar or settings panel:

import { ThemeSwitcher } from '@/components/ThemeSwitcher';

<ThemeSwitcher />

Theming System (v0.2)

The GUI ships with a CSS-variable-based theming system in gui/src/themes/.

Built-in Themes

Architecture

• ThemeProvider -- React context provider that applies the active theme's CSS variables to the document root. Supports runtime switching without page reload.
• CSS Variable Bridge -- All colors, spacing, and typography are exposed as --weftos-* CSS custom properties. Tailwind classes reference these variables, so switching themes updates the entire UI instantly.
• ANSI Palette Mapping -- Terminal and code blocks map ANSI color codes to the active theme's palette, ensuring consistent appearance across themes.
• Tailwind Integration -- The tailwind.config.ts extends Tailwind's color palette with --weftos-* custom properties, so utility classes like bg-weftos-surface and text-weftos-primary respond to theme changes automatically.

Custom Themes

Create a new theme by defining a CSS file with --weftos-* custom properties and registering it with the ThemeProvider:

import { registerTheme } from '@/themes';

registerTheme('my-theme', {
  '--weftos-bg': '#1a1a2e',
  '--weftos-surface': '#16213e',
  '--weftos-primary': '#0f3460',
  '--weftos-accent': '#e94560',
  '--weftos-text': '#eaeaea',
  // ... full palette
});

Implementation Roadmap

• K8.1: Tauri 2.0 scaffolding + basic Rust-to-TS bindings (ServiceApi exposure, RegistryQueryService, etc.)
• K8.2: Core dashboards (service map, mesh topology, chain viewer) with 2D graphs
• K8.3: 3D ECC visualization with React Three Fiber; score-driven dynamic styling
• K8.4: Dynamic app loading + Weaver integration for generating TS apps
• K8.5: Governance integration, partial-data handling, and self-introspection features
• K8.6: Polish (native feel, multi-window, theming, distributable apps) + testing across platforms

See Also

• ECC -- cognitive substrate that powers the knowledge graph
• Governance -- the governance engine that gates GUI actions
• Mesh Networking -- mesh topology the GUI visualizes