feat(vscode): add governance visualization system

packages/agent-os-vscode/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to the Agent OS VS Code extension will be documented in this file.
+
+## [1.1.0] - 2026-03-25
+
+### Security
+- Rate limiting added to GovernanceServer (100 requests/minute per client)
+- Session token authentication for WebSocket connections
+- Bundled D3.js v7.8.5 and Chart.js v4.4.1 locally (removed CDN dependency on cdn.jsdelivr.net)
+- Eliminated innerHTML XSS vectors via shared `escapeHtml` utility across all legacy panels
+- Pinned axios (1.13.6) and ws (8.20.0) to exact versions for reproducible builds
+- Python path validation: rejects shell metacharacters before subprocess spawn
+- axios retained over VS Code built-in fetch: provides timeout, maxContentLength, and maxRedirects guards not available in built-in fetch API
+
+### Removed
+- `S3StorageProvider` - Cloud export to AWS S3 (stub, never implemented)
+- `AzureBlobStorageProvider` - Cloud export to Azure Blob Storage (stub, never implemented)
+- Backend service layer (out of scope for this release)
+
+### Added
+- Live governance data: auto-detects and starts agent-failsafe REST server on activation
+- Auto-install: prompts to install agent-failsafe[server] from PyPI if not found
+- Connection indicator in status bar: Live, Stale, Disconnected
+- Input validation on all REST responses with type checking, size caps, string truncation
+- Loopback enforcement: governance endpoint restricted to 127.0.0.1/localhost/::1
+- Governance Hub: Unified sidebar webview with SLO, topology, and audit tabs
+- SLO Dashboard: Rich webview panel with availability, latency, compliance, and trust score metrics
+- Agent Topology: Force-directed graph panel showing agent mesh, trust rings, and bridges
+- Browser experience: Local dev server serves governance dashboard in external browser
+- Governance status bar: Mode indicator, execution ring, connection status
+- Policy diagnostics: Real-time governance rule validation with code actions
+- Local report export: Self-contained HTML governance report
+- Metrics exporter: Push dashboard metrics to observability endpoints
+- 3-slot configurable sidebar replacing 8 stacked tree views with React + Tailwind panel system
+- Panel picker overlay for drag-and-drop slot configuration
+- GovernanceStore: centralized state management with JSON deduplication and visibility gating
+- Event-driven refresh: sidebar reacts instantly to data changes via vscode.EventEmitter, 30s heartbeat safety net
+- Scanning mode: 4-second auto-rotation through sidebar slots with hover/focus pause and prefers-reduced-motion support
+- Attention toggle: Manual/Auto switch — manual locks to user config, auto enables scanning and priority reordering
+- Priority engine: ranks panels by health urgency (critical > warning > healthy > unknown), auto-reorders slots in auto mode
+- Per-panel latency isolation: slow data sources automatically split to offset refresh cadence with staleness indicator
+
+### Changed
+- SLO Dashboard, Agent Topology, and Governance Hub panels migrated from HTML template strings to React + Tailwind
+- Panel host classes replaced with shared `panelHost.ts` factory (280 lines of duplication removed)
+- GovernanceStore data fetches parallelized via Promise.all (latency: sum of all sources → max)
+- ForceGraph DOM rendering optimized (build elements once, update positions per frame)
+- Refresh commands (`refreshSLO`, `refreshTopology`) now route through GovernanceStore
+- SidebarProvider refactored from monolithic 213-line data owner to 133-line thin webview bridge
+- Sidebar polling replaced with event-driven architecture — LiveSREClient and AuditLogger emit change events
+
+### Removed
+- Legacy tree view commands: `showSLODashboard`, `showAgentTopology` (replaced by `showSLOWebview`, `showTopologyGraph`)
+- Legacy HTML template panels: SLODashboardPanel, TopologyGraphPanel, GovernanceHubPanel (replaced by React detail panels)
+- Legacy hub formatters: hubSLOFormatter, hubTopologyFormatter, hubAuditFormatter, hubAuditHelpers
+
+### Fixed
+- Path traversal vulnerability in LocalStorageProvider (export directory escape)
+- KernelDebuggerProvider 1-second timer never disposed (memory/CPU leak)
+- GovernanceStore detail subscriptions leaked empty Sets on dispose
+- Panel host title HTML injection vulnerability (now stripped)
+
+## [1.0.1] - 2026-01-29
+
+### Fixed
+- Workflow Designer: Delete button now works correctly on nodes
+- Workflow Designer: Code generation handles empty workflows gracefully
+- Workflow Designer: TypeScript and Go exports have proper type annotations
+
+## [1.0.0] - 2026-01-28
+
+### Added - GA Release 🎉
+- **Policy Management Studio**: Visual policy editor with templates
+  - 5 built-in templates (Strict Security, SOC 2, GDPR, Development, Rate Limiting)
+  - Real-time validation
+  - Import/Export in YAML format
+
+- **Workflow Designer**: Drag-and-drop agent workflow builder
+  - 4 node types (Action, Condition, Loop, Parallel)
+  - 8 action types (file_read, http_request, llm_call, etc.)
+  - Code export to Python, TypeScript, Go
+  - Policy attachment at node level
+
+- **Metrics Dashboard**: Real-time monitoring
+  - Policy check statistics
+  - Activity feed with timestamps
+  - Export to CSV/JSON
+
+- **IntelliSense & Snippets**
+  - 14 code snippets for Python, TypeScript, YAML
+  - Context-aware completions for AgentOS APIs
+  - Hover documentation
+
+- **Security Diagnostics**
+  - Real-time vulnerability detection
+  - 13 security rules (os.system, eval, exec, etc.)
+  - Quick fixes available
+
+- **Enterprise Features**
+  - SSO integration (Azure AD, Okta, Google, GitHub)
+  - Role-based access control (5 roles)
+  - CI/CD integration (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, CircleCI)
+  - Compliance frameworks (SOC 2, GDPR, HIPAA, PCI DSS)
+
+- **Onboarding Experience**
+  - Interactive getting started guide
+  - Progress tracking
+  - First agent tutorial
+
+### Changed
+- Upgraded extension architecture for GA stability
+- Improved WebView performance
+
+## [0.1.0] - 2026-01-27
+
+### Added
+- Initial release
+- Real-time code safety analysis
+- Policy engine with 5 policy categories:
+  - Destructive SQL (DROP, DELETE, TRUNCATE)
+  - File deletes (rm -rf, unlink, rmtree)
+  - Secret exposure (API keys, passwords, tokens)
+  - Privilege escalation (sudo, chmod 777)
+  - Unsafe network calls (HTTP instead of HTTPS)
+- CMVK multi-model code review (mock implementation for demo)
+- Audit log sidebar with recent activity
+- Policies view showing active policies
+- Statistics view with daily/weekly counts
+- Status bar with real-time protection indicator
+- Team policy sharing via `.vscode/agent-os.json`
+- Export audit log to JSON
+- Custom rule support
+
+### Known Limitations
+- CMVK uses mock responses (real API integration planned)
+- Inline completion interception is read-only (doesn't block)
+- Limited to text change detection for now

packages/agent-os-vscode/HELP.md

@@ -0,0 +1,140 @@
+# Agent OS for VS Code -- Help
+
+## Overview
+
+Agent OS provides kernel-level governance for AI coding assistants running inside VS Code.
+It enforces policies in real time, audits every AI suggestion, and visualizes the health
+of your agent mesh through a set of sidebar panels and detail views.
+
+---
+
+## Panels
+
+### SLO Dashboard (Sidebar)
+
+Displays Service Level Objective health for the governance kernel. Four metric groups:
+
+| Metric | Meaning |
+|---|---|
+| Availability | Percentage of successful governance evaluations over the current window. |
+| Latency P50 / P95 / P99 | Response time percentiles for policy evaluation calls (milliseconds). |
+| Compliance | Percentage of tool calls that passed policy evaluation without violations. |
+| Trust Score | Mean and minimum trust scores across all registered agents (0--1000 scale). |
+
+Click the panel header to open the **SLO Detail** view with burn-rate sparklines and error budget gauges.
+
+### Topology (Sidebar)
+
+Shows the agent mesh as a list of registered agents, protocol bridges (A2A, MCP, IATP),
+and delegation chains. Each agent entry displays its DID, trust score, and execution ring.
+
+Click the panel header to open the **Topology Detail** view with a force-directed graph.
+
+### Audit Log (Sidebar)
+
+Scrollable list of recent governance events: tool calls evaluated, blocked, warned, or allowed.
+Each entry shows timestamp, action, agent DID, affected file, and severity badge.
+
+### Policies (Sidebar)
+
+Lists all active policy rules with their action (ALLOW / DENY / AUDIT / BLOCK), match pattern,
+evaluation count, and violation count for the current day.
+
+### Stats (Sidebar)
+
+Aggregate counters: total tool calls blocked, warnings issued, CMVK reviews triggered,
+and total log entries. Refreshes on the same tick as all other panels.
+
+### Kernel Debugger (Sidebar)
+
+Live view of kernel internals: registered agents, active violations, saga checkpoints,
+and kernel uptime. Useful for diagnosing why a tool call was blocked or escalated.
+
+### Memory Browser (Sidebar)
+
+Virtual filesystem browser showing the episodic memory kernel (EMK) contents.
+Navigate directories and inspect files stored by agents during execution.
+
+### Governance Hub (Detail)
+
+Composite view combining SLO, topology, audit, and policy data in a tabbed interface.
+Provides a single-pane-of-glass overview of governance health. Tabs: Overview, SLO,
+Topology, Audit, Policy.
+
+### SLO Detail (Detail)
+
+Full SLO view with:
+- Availability and latency gauges against their targets.
+- Error budget remaining bars for availability and latency.
+- 24-point burn-rate sparkline showing consumption trend.
+- Trust score distribution histogram (4 buckets: 0--250, 251--500, 501--750, 751--1000).
+
+### Topology Detail (Detail)
+
+Force-directed graph of the agent mesh. Nodes are agents colored by trust tier.
+Edges represent delegation chains labeled with the delegated capability.
+Bridge status indicators show connected protocol bridges.
+
+### Policy Detail (Detail)
+
+Table of all policy rules with columns: name, action, pattern, enabled, evaluations today,
+violations today. Sortable and filterable.
+
+---
+
+## Glossary
+
+| Term | Definition |
+|---|---|
+| SLO | Service Level Objective -- a target for a measurable reliability metric. |
+| SLI | Service Level Indicator -- the measured value that an SLO tracks. |
+| P50 / P95 / P99 | Latency percentiles. P99 = 99% of requests are faster than this value. |
+| Burn Rate | How fast the error budget is being consumed. 1.0 = on pace to exhaust exactly at window end. |
+| Error Budget | Allowed unreliability. If target is 99.9%, the budget is 0.1% of total requests. |
+| Trust Score | Numeric reputation of an agent (0--1000). Derived from behavioral signals via reward scoring. |
+| Trust Ring | Concentric tiers grouping agents by trust level for visualization (high, medium, low). |
+| DID | Decentralized Identifier. Format: `did:mesh:<hash>` (toolkit) or `did:myth:<persona>:<hash>` (FailSafe). |
+| CMVK | Constitutional Multi-Model Verification Kernel. Cross-checks AI output with multiple models. |
+| Delegation Chain | A directed trust relationship where one agent grants a capability to another. |
+| Bridge | Protocol adapter connecting Agent Mesh to external systems (A2A, MCP, IATP). |
+| CSP | Content Security Policy. HTTP header restricting resource loading in webviews. |
+| Policy Action | Evaluation result: ALLOW (permit), DENY (reject), AUDIT (permit + log), BLOCK (reject + alert). |
+| Execution Ring | Privilege tier from hypervisor: Ring 0 (root), Ring 1 (supervisor), Ring 2 (user), Ring 3 (sandbox). |
+| Agent Mesh | The network of registered agents, their identities, trust scores, and interconnections. |
+| Saga | A multi-step workflow with checkpoints and compensating actions managed by the hypervisor. |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Status bar shows **Disconnected** | WebSocket connection to local governance server dropped. | Check that the server is running (`Agent OS: Start Server` command). Verify port 9845 is not blocked. |
+| Panel header shows **Stale** | Last data refresh was more than 2 tick intervals ago. | Click the refresh icon on the panel. If persistent, restart the extension host. |
+| Panel shows **Waiting for data...** | First data fetch has not completed yet. | Wait 10 seconds for the first broadcast cycle. If it persists, the mock backend may have failed to initialize. |
+| Topology graph is empty | No agents are registered in the mock or live backend. | Ensure the topology data provider is configured. In dev mode, the mock backend seeds 4 agents automatically. |
+| SLO shows 0% availability | The SLO provider returned a zeroed snapshot. | This usually means the provider has not received any evaluation events. Trigger a policy evaluation or restart. |
+| Browser dashboard not loading | Server failed to bind to 127.0.0.1. | Run `Agent OS: Start Server` and check the Output panel for port conflict messages. |
+
+---
+
+## Security Design Decisions
+
+| Decision | Rationale | Risk Level |
+|---|---|---|
+| `'unsafe-inline'` for `style-src` in CSP | Required for VS Code theme CSS variable injection (`var(--vscode-*)`). Scripts remain nonce-gated. | Low -- style-only; no script injection vector. |
+| `retainContextWhenHidden: true` on Topology Detail | Preserves force-simulation state across tab switches (~120 animation frames). | Low -- adds ~2 MB memory when backgrounded. |
+| Session token in WebSocket URL query string | WebSocket upgrade requests cannot carry custom headers (RFC 6455). Token is 128-bit `crypto.randomBytes`. | Low -- server binds to 127.0.0.1; token never leaves loopback. |
+| Rate limiter Map without TTL eviction | Server is loopback-only, so the map holds at most one entry (127.0.0.1). | Negligible -- no memory growth risk. |
+| `Math.random()` for burn-rate sparkline jitter | Synthetic demo data only, not used for any security or cryptographic purpose. | None -- replaced by real SRE data when backend connects. |
+| `axios` not used; `http` module for server | The governance server uses Node built-in `http`. No external HTTP client dependency. | N/A |
+
+---
+
+## Configuration Reference
+
+All extension settings are documented in the [README](README.md) under the **Extension Settings** section.
+Key settings are prefixed with `agent-os.` in VS Code's Settings UI.
+
+For policy file configuration, see the Agent OS documentation on policy schemas:
+`packages/agent-os/src/agent_os/policies/schema.py`.