feat(vscode): add governance visualization system

[MythologIQ]

Summary

Adds a complete governance visualization system to the VS Code extension at packages/agent-os-vscode/ (aligned with #546):

• Governance Server — REST API with browser experience for real-time policy, SLO, and topology data
• 3-Slot React Sidebar — Unified panel system replacing 8 tree views, with GovernanceStore event bus, priority engine, and scanning mode
• SLO Dashboard — Detail panel with gauge charts, sparklines, and error budget visualization
• Topology Graph — D3.js force-directed graph with agent/bridge drilldowns
• Governance Hub — Tabbed audit log and policy browser with filtering
• Language Intelligence — Diagnostics, code actions, and governance rules for policy YAML files
• Export System — HTML report generation with local storage
• Observability — OpenTelemetry-compatible metrics exporter
• 498 tests passing across 37 test files

Security

• All CDN dependencies bundled locally (assets/vendor/d3.v7.8.5.min.js, assets/vendor/chart.v4.4.1.umd.min.js)
• All innerHTML assignments use escapeHtml() utility or inline esc() with full character coverage
• CSP nonces applied to all webview panels (including legacy MetricsDashboard, Onboarding, PolicyEditor, WorkflowDesigner)
• Upstream security fixes from fix(security): address VS Code extension vulnerabilities — prototype pollution, token exposure, ReDoS, missing CSP #489 integrated: prototype pollution protection, token-in-SecretStorage, ReDoS-safe regex
• No secrets, no environment-specific paths

Addresses reviewer feedback

Per review comments on the prior PR:

• Rebased against packages/agent-os-vscode/ location (aligned with refactor: extract VS Code extension to packages/agent-os-vscode/ (#491) #546)
• CDN dependencies bundled locally
• innerHTML assignments sanitized
• Security fixes from fix(security): address VS Code extension vulnerabilities — prototype pollution, token exposure, ReDoS, missing CSP #489 integrated

Test plan

• npm run compile — TypeScript + React/Tailwind pipeline clean
• npm run lint — ESLint clean (warnings only, matching upstream baseline)
• npm test — 498 tests passing (37 test suites)
• Manual: Launch Extension Development Host (F5), verify sidebar renders with mock data
• Manual: Open SLO Detail, Topology Graph, Governance Hub panels
• Manual: Verify browser experience at localhost governance server

Closes #491

🤖 Generated with Claude Code

[github-actions]

🤖 AI Agent: breaking-change-detector — Summary

🔍 API Compatibility Report

Summary

This pull request primarily adds new features to the agent-os-vscode package, including a governance visualization system, security hardening, and live governance data integration. No breaking changes were identified in the public API of the microsoft/agent-governance-toolkit repository.

Findings

Severity	Package	Change	Impact
✅	agent-os-vscode	No breaking changes	No impact on existing API consumers

Migration Guide

No migration steps are necessary as no breaking changes were identified.

Notes

• The changes are additive in nature, introducing new features and functionality without altering existing APIs.
• The added functionality should be documented thoroughly to ensure users can take full advantage of the new features.

If you have further questions or need additional analysis, feel free to ask!

[github-actions]

🤖 AI Agent: docs-sync-checker — Issues Found

📝 Documentation Sync Report

Issues Found

• ❌ GovernanceServer in packages/agent-os-vscode/src/server.ts — missing docstring
• ❌ GovernanceStore in packages/agent-os-vscode/src/store.ts — missing docstring
• ❌ escapeHtml() in packages/agent-os-vscode/src/utils.ts — missing docstring
• ❌ panelHost.ts in packages/agent-os-vscode/src/panels/panelHost.ts — missing docstring for the factory function
• ⚠️ packages/agent-os-vscode/README.md — The "Configuration" section should include details about the new agentOS.governance.refreshIntervalMs setting.
• ⚠️ packages/agent-os-vscode/README.md — The "Commands" section should include descriptions for the newly added commands, such as Agent OS: Open Governance Hub.
• ⚠️ CHANGELOG.md — No entry for the addition of the escapeHtml() utility function.
• ⚠️ examples/ — No updates to example code to demonstrate the new governance visualization system.

Suggestions

• 💡 Add docstrings for the following:
  • GovernanceServer class in packages/agent-os-vscode/src/server.ts to explain its purpose, methods, and any parameters or exceptions.
  • GovernanceStore class in packages/agent-os-vscode/src/store.ts to describe its role in state management, its methods, and how it interacts with other components.
  • escapeHtml(input: str) -> str in packages/agent-os-vscode/src/utils.ts to explain its purpose (e.g., preventing XSS) and the expected input/output.
  • The factory function in panelHost.ts to describe its purpose and parameters.
• 💡 Update the "Configuration" section in packages/agent-os-vscode/README.md to include the new agentOS.governance.refreshIntervalMs setting and its purpose.
• 💡 Add descriptions for the new commands in the "Commands" section of packages/agent-os-vscode/README.md.
• 💡 Add an entry in CHANGELOG.md for the escapeHtml() utility function, as it is a new addition with security implications.
• 💡 Update example code in the examples/ directory to demonstrate how to use the new governance visualization system, including the new commands and features.

Additional Notes

• The CHANGELOG.md file is comprehensive and includes detailed entries for most of the changes introduced in this PR. However, the escapeHtml() utility function is not explicitly mentioned, and it should be added due to its importance in preventing XSS vulnerabilities.
• The README.md has been updated to include a "What's New in v1.1.0" section, which is helpful. However, the "Configuration" and "Commands" sections need to be updated to reflect the new settings and commands introduced in this PR.
• The HELP.md file is thorough and provides detailed documentation for the new features, which is excellent.
• Ensure all new public APIs have complete type annotations.

Please address the issues and suggestions above to ensure the documentation is fully in sync with the changes introduced in this PR. Let me know if you need further assistance!

[github-actions]

🤖 AI Agent: code-reviewer

Review Feedback for PR: feat(vscode): add governance visualization system

---

🔴 CRITICAL: Security Issues

1. Session Token in WebSocket URL Query String

   • While the WebSocket server binds to 127.0.0.1, storing session tokens in the URL query string is inherently insecure. Query strings can be logged by proxies, debugging tools, or browser history. Even though the server is loopback-only, this practice violates security best practices.
   • Actionable Fix: Use WebSocket subprotocols or custom headers for session token authentication instead of query strings.

2. Rate Limiter Map Without TTL Eviction

   • The rate limiter uses a Map without TTL eviction. While the server is loopback-only, this design could lead to memory exhaustion if the server is exposed to external traffic due to misconfiguration.
   • Actionable Fix: Implement TTL-based eviction for the rate limiter map to prevent unbounded memory growth.

3. CSP Style-src Unsafe-inline

   • The CSP allows 'unsafe-inline' for style-src to support VS Code theme CSS injection. While scripts remain nonce-gated, this weakens the CSP and could allow style-based XSS attacks if combined with other vulnerabilities.
   • Actionable Fix: Investigate alternatives to 'unsafe-inline', such as using hashed styles or precomputed CSS variables.

4. Python Path Validation

   • The subprocess lifecycle validates Python paths to reject shell metacharacters. However, this validation is insufficient to prevent command injection in edge cases (e.g., paths containing special characters that bypass regex checks).
   • Actionable Fix: Use shlex.quote() or equivalent to sanitize paths before subprocess invocation.

---

🟡 WARNING: Potential Breaking Changes

1. Legacy Commands Removed

   • Commands like showSLODashboard and showAgentTopology have been replaced by new webview-based commands (showSLOWebview, showTopologyGraph). This could break workflows for users relying on the old commands.
   • Actionable Fix: Provide backward compatibility by aliasing old commands to the new ones or documenting migration steps clearly.

2. Governance Server Auto-Install

   • The extension prompts users to install agent-failsafe[server] from PyPI if not found. This introduces a dependency on Python and pip, which may not be available in all environments.
   • Actionable Fix: Add a fallback mechanism or provide clear error messages for environments without Python/pip.

---

💡 Suggestions for Improvement

1. Type Safety in GovernanceStore

   • The GovernanceStore uses event-driven refresh mechanisms but lacks explicit type annotations for its data models. This could lead to runtime errors in edge cases.
   • Suggestion: Use TypeScript interfaces or classes to enforce type safety for GovernanceStore data models.

2. OpenTelemetry Metrics Exporter

   • The metrics exporter supports OpenTelemetry-compatible endpoints but does not validate endpoint configurations. Misconfigured endpoints could lead to silent failures.
   • Suggestion: Add validation for observability endpoint configurations and log warnings for invalid setups.

3. Sandbox Escape Vectors

   • The Governance Server subprocess lifecycle spawns Python processes. While paths are validated, additional sandboxing (e.g., using subprocess.Popen with restricted permissions) could further reduce escape risks.
   • Suggestion: Investigate using containerized subprocess execution (e.g., Docker) for enhanced isolation.

4. Backward Compatibility for Tree Views

   • The new 3-slot React sidebar replaces 8 tree views. While this improves usability, users accustomed to the old layout may face a learning curve.
   • Suggestion: Provide a "legacy mode" toggle to temporarily restore the old tree view layout.

5. Governance Hub Accessibility

   • The Governance Hub uses scanning mode with auto-rotation and hover/focus pause. While this respects prefers-reduced-motion, additional accessibility features (e.g., keyboard navigation) could improve usability.
   • Suggestion: Add keyboard shortcuts for navigating between tabs and panels.

---

Summary of Changes

• Security: Address critical issues like session token handling, CSP weaknesses, and subprocess validation.
• Breaking Changes: Mitigate impact by aliasing old commands and documenting migration paths.
• Improvements: Enhance type safety, sandboxing, and accessibility.

This PR introduces significant functionality and security improvements but requires fixes to address critical vulnerabilities and backward compatibility concerns.

[github-actions]

🤖 AI Agent: contributor-guide — Welcome to the project! 🎉

Welcome to the project! 🎉

Hi @first-time-contributor! Thank you so much for taking the time to contribute to the microsoft/agent-governance-toolkit repository. We’re thrilled to have you here, and we deeply appreciate the effort you’ve put into this pull request. It’s always exciting to see new contributors join the community!

---

What You Did Well 🌟

1. Comprehensive Feature Addition: Your governance visualization system is a significant and well-thought-out addition to the project. The detailed description of the features (e.g., the React sidebar, SLO dashboard, topology graph, and governance hub) shows the depth of your work. The inclusion of 498 passing tests is particularly impressive and demonstrates your commitment to quality.

2. Security Considerations: Your attention to security is commendable. Bundling CDN dependencies locally, sanitizing innerHTML assignments, applying CSP nonces, and integrating upstream security fixes are all excellent practices that align with our project’s focus on security.

3. Thorough Documentation: The detailed updates to the README.md, HELP.md, and SECURITY.md files are fantastic. They provide clear guidance for users and contributors, which is essential for an open-source project.

4. Addressing Feedback: It’s great to see that you’ve addressed feedback from the previous PR. This shows your dedication to improving the project and collaborating effectively.

---

Suggestions for Improvement ✨

While your PR is excellent, there are a few areas where we can refine it further:

1. Linting: We use ruff for linting in this project, specifically with the E, F, and W rules enabled. Please ensure that your code passes the ruff linter. You can run ruff . in the root directory to check for any issues. If you encounter any errors, you can refer to the ruff documentation for guidance.

2. Tests Location: While you’ve done an excellent job with the 498 tests, please ensure that all new test files are placed in the packages/{name}/tests/ directory, as per our project conventions. This helps us keep the repository organized and maintainable.

3. Commit Messages: We follow the Conventional Commits specification for commit messages. While your PR title is correctly prefixed with feat:, please ensure that all individual commit messages in this PR follow the same convention. For example:

   • feat(vscode): add governance visualization system
   • fix(vscode): sanitize innerHTML assignments to prevent XSS
   • docs(vscode): update README with governance visualization details

4. Manual Testing Checklist: While you’ve included a manual test plan, it would be helpful to confirm that you’ve completed the manual tests listed (e.g., verifying the sidebar renders with mock data, opening the SLO Detail panel, etc.). If you haven’t had a chance to test these yet, feel free to let us know, and we can assist with testing.

---

Project Conventions 📚

Here’s a quick recap of some key conventions we follow in this project:

• Linting: We use ruff for linting with E, F, and W rules enabled. Please ensure your code passes ruff checks.
• Testing: All test files should be placed in the packages/{name}/tests/ directory.
• Commit Messages: Follow the Conventional Commits format (e.g., feat:, fix:, docs:, etc.).
• Security: Security-sensitive code gets extra scrutiny. Your PR already demonstrates excellent attention to security, but we’ll review it further to ensure compliance with our standards.

For more details, please refer to our CONTRIBUTING.md and QUICKSTART.md guides.

---

Next Steps 🚀

1. Address Feedback: Please review the suggestions above and make any necessary updates to your PR.
2. Run Linter: Ensure your code passes ruff checks.
3. Confirm Manual Tests: Let us know if you’ve completed the manual tests or need assistance with them.
4. Update Commit Messages: If needed, update your commit messages to follow the Conventional Commits format.

Once you’ve made these updates, let us know, and we’ll take another look. If you have any questions or need help with anything, don’t hesitate to ask. We’re here to support you!

Thank you again for your contribution — we’re excited to work with you on this! 😊

[github-actions]

🤖 AI Agent: security-scanner — Security Review of PR: feat(vscode): add governance visualization system

Security Review of PR: feat(vscode): add governance visualization system

This PR introduces a governance visualization system for the Agent OS VS Code extension, including a REST API, React-based UI components, and various security enhancements. Below is a detailed security analysis based on the provided code and documentation.

---

Findings

1. Prompt Injection Defense Bypass

• Risk: The PR mentions the use of escapeHtml() for sanitizing innerHTML assignments to prevent XSS. However, it is unclear if this utility is robust against all edge cases (e.g., nested escaping, Unicode normalization attacks).
• Attack Vector: If escapeHtml() fails to sanitize certain inputs, an attacker could inject malicious scripts into the webview, potentially compromising the user's system.
• Rating: 🟠 HIGH
• Recommendation:
  • Conduct a thorough review of the escapeHtml() utility to ensure it handles all edge cases.
  • Consider using a library like DOMPurify for sanitizing HTML, as it is widely used and well-tested.
  • Add automated tests to validate the effectiveness of the sanitization process.

---

2. Policy Engine Circumvention

• Risk: The PR does not provide sufficient details about how the policy engine integrates with the new visualization system. There is a risk that the visualization system could expose sensitive policy data or allow unauthorized modifications.
• Attack Vector: If the REST API or GovernanceStore does not enforce proper access controls, an attacker could manipulate or bypass policies by exploiting the visualization system.
• Rating: 🔴 CRITICAL
• Recommendation:
  • Ensure that all REST API endpoints are protected with proper authentication and authorization mechanisms.
  • Implement role-based access control (RBAC) for sensitive operations.
  • Perform a thorough review of the GovernanceStore and REST API to ensure that policies cannot be bypassed or modified without proper authorization.

---

3. Trust Chain Weaknesses

• Risk: The PR does not mention any specific mechanisms for validating the trustworthiness of agents in the topology graph or the governance server. This could lead to trust chain weaknesses.
• Attack Vector: An attacker could inject malicious agents or manipulate trust scores to compromise the integrity of the agent mesh.
• Rating: 🟠 HIGH
• Recommendation:
  • Implement strict validation of agent identities using cryptographic methods (e.g., SPIFFE/SVID).
  • Ensure that trust scores are calculated and stored securely, and cannot be tampered with by malicious actors.
  • Add logging and monitoring for any anomalies in trust score updates or agent registrations.

---

4. Credential Exposure

• Risk: The PR mentions session tokens for WebSocket authentication but does not specify how these tokens are stored or managed. If tokens are logged or exposed, they could be used to hijack sessions.
• Attack Vector: An attacker with access to logs or memory dumps could extract session tokens and use them to impersonate a legitimate user.
• Rating: 🟠 HIGH
• Recommendation:
  • Ensure that session tokens are stored securely in memory and are not logged.
  • Implement token expiration and rotation mechanisms.
  • Use secure, HTTP-only cookies for session management instead of query strings in WebSocket URLs.

---

5. Sandbox Escape

• Risk: The PR mentions subprocess management for the agent-failsafe server but does not detail how the subprocess is sandboxed. This could lead to a sandbox escape if the subprocess is compromised.
• Attack Vector: If an attacker exploits a vulnerability in the agent-failsafe server, they could execute arbitrary code on the host system.
• Rating: 🔴 CRITICAL
• Recommendation:
  • Use a secure sandboxing mechanism (e.g., seccomp, AppArmor, or SELinux) to isolate the subprocess.
  • Validate all inputs to the subprocess to prevent command injection.
  • Run the subprocess with the least privileges necessary.

---

6. Deserialization Attacks

• Risk: The PR mentions REST responses being validated with type checking, size caps, and string truncation. However, it is unclear if deserialization is handled securely.
• Attack Vector: If the REST API processes untrusted JSON or other serialized data without proper validation, an attacker could exploit deserialization vulnerabilities to execute arbitrary code.
• Rating: 🟠 HIGH
• Recommendation:
  • Use a safe JSON parser that does not execute arbitrary code during deserialization.
  • Validate all deserialized data against a strict schema before processing.
  • Add tests to ensure that malicious payloads are rejected.

---

7. Race Conditions

• Risk: The PR introduces event-driven refresh mechanisms and a priority engine for panel updates. There is a risk of time-of-check-to-time-of-use (TOCTOU) vulnerabilities if state changes are not properly synchronized.
• Attack Vector: An attacker could exploit race conditions to manipulate governance data or bypass policy checks.
• Rating: 🟡 MEDIUM
• Recommendation:
  • Use locks or atomic operations to ensure thread safety in the GovernanceStore and event-driven refresh mechanisms.
  • Conduct a detailed review of the priority engine to identify potential race conditions.

---

8. Supply Chain Risks

• Risk: The PR mentions that all CDN dependencies (D3.js, Chart.js) are bundled locally, which mitigates some supply chain risks. However, the PR does not specify if these dependencies are verified or if their integrity is checked.
• Attack Vector: If the bundled dependencies are tampered with or replaced by malicious versions, they could introduce vulnerabilities into the system.
• Rating: 🟡 MEDIUM
• Recommendation:
  • Use tools like npm audit to regularly scan for vulnerabilities in dependencies.
  • Implement Subresource Integrity (SRI) checks for all bundled assets.
  • Consider using a tool like snyk or dependabot to monitor for vulnerabilities in dependencies.

---

Summary of Findings

Category	Risk	Rating
Prompt Injection Defense Bypass	XSS via innerHTML	🟠 HIGH
Policy Engine Circumvention	Unauthorized policy modification	🔴 CRITICAL
Trust Chain Weaknesses	Agent identity and trust score manipulation	🟠 HIGH
Credential Exposure	Session token leakage	🟠 HIGH
Sandbox Escape	Subprocess compromise	🔴 CRITICAL
Deserialization Attacks	Unsafe JSON handling	🟠 HIGH
Race Conditions	TOCTOU in event-driven refresh	🟡 MEDIUM
Supply Chain Risks	Dependency tampering	🟡 MEDIUM

---

General Recommendations

1. Comprehensive Security Testing: Conduct penetration testing and fuzzing on the REST API, GovernanceStore, and subprocess management.
2. Code Reviews: Perform a detailed code review of the escapeHtml() utility, REST API, and subprocess management code.
3. Automated Security Scans: Integrate tools like snyk, OWASP ZAP, and Bandit into the CI/CD pipeline to catch vulnerabilities early.
4. Documentation: Update the documentation to include details about the security measures in place, such as token management, sandboxing, and input validation.

This PR introduces significant functionality but also carries critical security risks that must be addressed before merging.

[MythologIQ]

Addressing Review Feedback from Prior PR

Hi @imsiddiquee — this is a fresh PR addressing all items from your review of the original submission. Here's a point-by-point response:

1. CDN Dependencies — Bundled Locally ✅

D3.js and Chart.js are no longer loaded from jsdelivr CDN. They are bundled as local vendor assets:

packages/agent-os-vscode/assets/vendor/
├── d3.v7.8.5.min.js        (D3 v7.8.5)
└── chart.v4.4.1.umd.min.js (Chart.js v4.4.1)

The browser template loads them from disk via the local governance server (browserTemplate.ts reads from assets/vendor/). Webview panels use the VS Code webview.asWebviewUri() API to reference local files. No external network requests for visualization libraries.

2. innerHTML XSS Patterns — Sanitized ✅

All innerHTML assignments in our new code use escape functions:

• browserScripts.ts — Inline esc() function escaping all 5 HTML-significant characters (& < > " '). Every dynamic value (agent DIDs, audit reasons, timestamps) passes through esc() before interpolation.
• ReportGenerator.ts — Same esc() pattern for generated HTML reports. All dynamic values escaped.
• escapeHtml.ts utility — Available for Node-side escaping.
• React panels (sidebar, SLO detail, topology, hub) — Use React's built-in XSS protection via JSX. No dangerouslySetInnerHTML anywhere.

The 4 legacy panels (MetricsDashboard, Onboarding, PolicyEditor, WorkflowDesigner) still use innerHTML with template literals — these are upstream baseline files. We've added CSP nonces to all of them (integrating your fix from #489), but full innerHTML remediation in those panels is a separate upstream concern.

3. Rebased Against packages/agent-os-vscode/ ✅

This PR places all files at packages/agent-os-vscode/ rather than the old packages/agent-os/extensions/vscode/ path. We used a transplant strategy (extract final state → move → clean commits) rather than a rebase to avoid conflicts with the directory rename in #546.

When #546 merges, this PR should rebase cleanly since our files are already at the target location.

4. Upstream Security Fixes Integrated ✅

All fixes from #489 are incorporated:

• CSP nonces on MetricsDashboard, Onboarding, PolicyEditor, WorkflowDesigner panels
• Prototype pollution protection in WorkflowDesigner (_updateNode allowlist)
• ReDoS-safe regex in PolicyEngine (safeRegExp wrapper)
• Token-in-SecretStorage in ssoProvider (stripped from globalState)
• policyCompletion.ts removed (replaced by language/completionProvider.ts)

Transition After #546

Once #546 merges and removes packages/agent-os/extensions/vscode/, this PR's commit 4 (refactor(vscode): extract extension to packages/agent-os-vscode/) handles the same rename — the delete side will become a no-op during rebase, leaving only our additions at the new location. We're happy to rebase once #546 lands.

Happy to address any additional feedback.

[MythologIQ]

Closing — premature submission. Will resubmit after #546 merges per reviewer guidance. Branch and work are ready for quick rebase once the directory move lands.