⚡ NAVA: Personal Agent Operating System

pip install nava-agent

NAVA is a deterministic, multi-agent personal operating system designed for autonomous workspace execution, secure computer use, deep research synthesis, and persistent human-AI collaboration.

Built around a 12-step mutation gateway, an inter-agent message bus, a 4-tier memory hierarchy, a dynamic Model Context Protocol (MCP) ecosystem of 15 specialized servers, and 21 certified system invariants, NAVA guarantees strict least-privilege bounding, tamper-evident audit receipts, and transactional rollback across all filesystem, terminal, browser, and OS desktop interactions.

---

📑 Table of Contents

1. System Architecture Overview
2. NAVA Root Kernel Controller
3. Model Context Protocol (MCP) Ecosystem (15 Servers)
4. Specialized Agent Suite
5. Core Codebase Isolation Invariant
6. On-Demand Memory Architecture
7. The 12-Step Chokepoint Action Gateway
8. Four-Tier Memory Hierarchy & AI Twin
9. The 21 Certified System Invariants
10. Configuration & User-Configurable Security Switches
11. Interactive TUI Cowork Shell
12. Repository Layout
13. Getting Started & Quickstart
14. Automated Verification & Test Suite

---

🏗️ System Architecture Overview

NAVA replaces unconstrained LLM prompt chains with a deterministic operating system kernel. Every tool call—whether modifying code, executing shell commands, clicking desktop GUI windows, compiling Typst documents, or querying external APIs via MCP—is treated as a managed system call subject to policy evaluation, risk scoring, resource quotas, and concurrency locking.

                           USER OBJECTIVE / SHELL
                                     │
                                     ▼
                    ┌─────────────────────────────────┐
                    │     NAVA ROOT ORCHESTRATOR      │
                    │   (Executive Kernel Controller) │
                    └────────────────┬────────────────┘
                                     │
                        Decompose Objective
                                     │
                                     ▼
                            [ GoalPlanner ]
                 Stage 1 (Parallel) ──► Stage 2 (Sequential)
                                     │
                                     ▼
                            [ AgentFactory ]
                 JIT Dynamic Synthesis & Scope Intersect:
            Child_Scope = Parent_Scope ∩ Spec_Scope ∩ Policy_Scope
                                     │
             ┌───────────────────────┴───────────────────────┐
             │                                               │
             ▼                                               ▼
┌──────────────────────────┐                   ┌──────────────────────────┐
│ SPECIALIZED STATIC AGENTS│                   │  DYNAMIC JIT SUBAGENTS   │
│ • CodingAgent            │◄─────────────────►│  • PDFIndexerAgent       │
│ • TerminalAgent (DevOps) │   Inter-Agent     │  • DataExtractionAgent   │
│ • ReviewerAgent (AST)    │   Message Bus     │  • SecurityAuditorAgent  │
│ • VerifierAgent (Proof)  │   (Pub/Sub)       │  • WebScraperAgent       │
│ • BrowserAgent (Web)     │                   │  • SuperpowersCodeAgent  │
│ • ComputerAgent (OS GUI) │                   │                          │
│ • UniversalFileAgent     │                   │                          │
└────────────┬─────────────┘                   └─────────────┬────────────┘
             │                                               │
             └───────────────────────┬───────────────────────┘
                                     │
                          Tool Request RPC Call
                                     │
                                     ▼
         ┌────────────────────────────────────────────────────────┐
         │            12-STEP ACTION GATEWAY PIPELINE             │
         │  1. Auth & Lineage Check    7. Pre-State Snapshot      │
         │  2. Policy Engine (ALLOW)   8. Sandboxed Tool Dispatch │
         │  3. Additive Risk Engine    9. Post-State Verification │
         │  4. Budget & Quota Check   10. Cryptographic Receipt   │
         │  5. Concurrency Locks      11. Lock Release & Teardown │
         │  6. HITL Gatekeeper        12. Episodic Memory Sync    │
         └───────────────────────────┬────────────────────────────┘
                                     │
                                     ▼
         ┌────────────────────────────────────────────────────────┐
         │                 HOST SYSTEM BOUNDARIES                 │
         │  • Isolated Project Files   • Playwright Headless Web  │
         │  • Ephemeral Docker Sandbox • OS Desktop GUI Perception│
         │  • 15 JSON-RPC MCP Servers  • Merkle Append-Only Ledger│
         └────────────────────────────────────────────────────────┘

---

👑 The NAVA Root Agent (Kernel Controller)

At the apex of the OS resides the NAVA Root Agent (src/nava/orchestrator.py), serving as the privileged executive supervisor:

┌────────────────────────────────────────────────────────────────────────┐
│                        NAVA ROOT AGENT KERNEL                          │
├────────────────────────────────────────────────────────────────────────┤
│  • Root Security Ceilings (nava.yaml)                                  │
│  • Stage & Parallel Goal Decomposition (GoalPlanner)                   │
│  • Subagent Lifecycle Supervisor (Spawn -> Observe -> Teardown)        │
│  • Global Task Budget Enforcement (Tokens, Steps, Depth, Retries)      │
│  • Project Workspace Context Continuator (.nava/project_memory.md)    │
│  • Out-of-Band Emergency Kill Switch Circuit Breaker                   │
└────────────────────────────────────────────────────────────────────────┘

1. Root Security Ceilings (Section 26)

Subagents spawned during task execution can never acquire permissions, credentials, or tool access beyond what is granted to the Root Agent in nava.yaml.

2. Hierarchical Execution Supervision

• Autonomous Task Staging: Decomposes complex human instructions into sequential stages ($1, 2, \dots, N$).
• Concurrent Subagent Dispatch: Executes independent sub-goals in parallel worker threads while maintaining shared state consistency.
• Deterministic Teardown: Upon task completion or failure, thread locks are released, temporary OAuth tokens revoked, and child states set to TERMINATED.

---

🌐 Model Context Protocol (MCP) Ecosystem (15 Servers)

NAVA implements the official standard Model Context Protocol (JSON-RPC 2.0 over stdio) via StdioMCPClient and MCPClientManager. Every server can be individually toggled via enabled: true / false in nava.yaml:

MCP Server	Assigned Roles	Package & Command	Capabilities & Tool Suite
context7	CodingAgent	npx -y @context7/mcp-server@latest	AST repository symbol graphs & context definition slicing (context7.get_symbol_graph, context7.slice_context).
superpowers	CodingAgent	uvx mcp-superpowers-code@latest	Syntax-aware structural code search, replacement, and compiler auto-fix (superpowers.ast_search, superpowers.ast_replace, superpowers.compiler_autofix).
git	CodingAgent, TerminalAgent	npx -y @modelcontextprotocol/server-git@latest	Project git branch inspection, diffs, staging, and commit operations (git.status, git.diff, git.branch, git.commit).
fetch	ResearchAgent	npx -y @modelcontextprotocol/server-fetch@latest	Token-dense HTML-to-Markdown page conversion and header inspection (fetch.get_markdown, fetch.get_raw_html, fetch.get_headers).
brave-search	ResearchAgent	npx -y @modelcontextprotocol/server-brave-search@latest	Web search and recent news queries (brave.search_web, brave.search_news).
arxiv	ResearchAgent	uvx mcp-server-arxiv@latest	Academic paper search, PDF retrieval, and abstract extraction (arxiv.search_papers, arxiv.get_paper_summary).
sqlite	DataAgent	uvx mcp-server-sqlite@latest	SQL query execution, table inspection, and schema profiling (sqlite.read_query, sqlite.write_query, sqlite.list_tables, sqlite.describe_tables).
typst	DocumentAgent, UniversalFileAgent	uvx typst-mcp-server@latest	Rust vector Typst compilation into PDF/DOCX reports (typst.compile_pdf, typst.render_template).
sequential-thinking	ReviewerAgent, VerifierAgent	npx -y @modelcontextprotocol/server-sequential-thinking@latest	Multi-branch hypothesis reasoning and thought revision (sequential_thinking.step).
audit-scanner	ReviewerAgent, VerifierAgent	uvx nava-audit-mcp@latest	Deterministic verification of NAVA's 21 System Invariants, AST security scanning, and factual report grounding (audit.verify_invariants, audit.security_scan, audit.verify_grounding).
docker-sandbox	TerminalAgent	uvx docker-sandbox-mcp@latest	Ephemeral container execution with CPU/memory limits and automatic purge (docker.create_sandbox, docker.exec_in_sandbox, docker.destroy_sandbox).
playwright-browser	BrowserAgent	npx -y @modelcontextprotocol/server-puppeteer@latest	Headless browser navigation, numbered interactive tree extraction ([#1], [#2]), viewport screenshotting, click/type/scroll (browser.navigate, browser.extract_interactive_tree, browser.screenshot, browser.click, browser.type, browser.scroll).
desktop-automation	ComputerAgent	uvx desktop-automation-mcp@latest	Display resolution perception, high-res desktop screenshots, mouse clicks, keystrokes, and keyboard hotkeys (desktop.get_screen_size, desktop.screenshot, desktop.click, desktop.type, desktop.hotkey).
gmail	EmailAgent	uvx gmail-mcp-server@latest	Email search, thread reading, and drafting (gmail.search, gmail.read).
github	GitHubAgent	npx -y @modelcontextprotocol/server-github@latest	Repository search, PR reviews, and issue creation (github.search_repositories, github.create_issue).

---

🤖 Specialized Agent Suite

NAVA includes a core suite of purpose-built static agents configured for dedicated workflows:

┌────────────────────────────────────────────────────────────────────────┐
│                     SPECIALIZED STATIC AGENT SUITE                     │
├────────────────────────────────────────────────────────────────────────┤
│  1. CodingAgent        AST refactoring, compiler auto-fix, batch edits │
│  2. ReviewerAgent      Security audits, AST vulnerability scan, diffs  │
│  3. VerifierAgent      21 System Invariants proof, grounding checks    │
│  4. ResearchAgent      Web crawling, paper search, semantic RAG        │
│  5. TerminalAgent      Shell execution, Docker sandboxing, test suites │
│  6. BrowserAgent       Playwright web automation & interactive trees   │
│  7. ComputerAgent      OS desktop perception & coordinate mouse/keys   │
│  8. DataAgent          SQL analysis, CSV profiling, anomaly detection  │
│  9. UniversalFileAgent Publication-grade Typst, DOCX, PPTX generation  │
└────────────────────────────────────────────────────────────## 🛡️ The 17-Step Chokepoint Action Gateway

Every mutating action in NAVA must pass sequentially through the 17-step `ActionGateway` chokepoint ([`src/nava/gateway/pipeline.py`](file:///c:/Users/aakhi/Desktop/Nava/src/nava/gateway/pipeline.py)):

                    INCOMING MUTATION REQUEST
                                │
                                ▼
 [ Step 0a: Emergency Circuit Check ] ──► Verifies Kill Switch Not Active
                                │
                                ▼
 [ Step 0b: Request Event Logging   ] ──► Emits TOOL_REQUESTED to Audit Ledger
                                │
                                ▼
 [ Step 1:  Schema Validation       ] ──► Validates Pydantic Arguments
                                │
                                ▼
 [ Step 2:  Agent Identity & TTL    ] ──► Validates UUID & Active Expiration
                                │
                                ▼
 [ Step 3:  Parent Scope Verify     ] ──► Non-Increasing Hierarchy (Inv #5)
                                │
                                ▼
 [ Step 4:  Permission Checking     ] ──► Confirms Permission Grant
                                │
                                ▼
 [ Step 5:  Policy Engine (ALLOW)   ] ──► Evaluates Rules & Security Switches
                                │
                                ▼
 [ Step 6:  Additive Risk Engine    ] ──► Computes Additive Risk Tier
                                │
                                ▼
 [ Step 7:  Budget Engine           ] ──► Verifies Tokens, Steps & Depth Quota
                                │
                                ▼
 [ Step 8:  Concurrency Locking     ] ──► Acquires Shared/Exclusive Locks
                                │
                                ▼
 [ Step 9:  Credential Brokerage    ] ──► Injects Scoped 5-min Secret Tokens
                                │
                                ▼
 [ Step 10: HITL Human Approval     ] ──► Prompts User for High Risk Approval
                                │
                                ▼
 [ Step 11: Pre-State Snapshot      ] ──► Captures Pre-Execution File Hash
                                │
                                ▼
 [ Step 12: Sandboxed Tool Exec     ] ──► Dispatches Tool Locally or via MCP
                                │
                                ▼
 [ Step 13: Post-State Observation  ] ──► Inspects Resource Mutation Output
                                │
                                ▼
 [ Step 14: Automated Verification  ] ──► Validates Size, Path & Integrity
                                │
                                ▼
 [ Step 15: Cryptographic Receipt   ] ──► Issues Signed Tamper-Evident Record
                                │
                                ▼
 [ Step 16: Audit Ledger Append     ] ──► Appends to Append-Only Ledger
                                │
                                ▼
 [ Step 17: Episodic Memory Sync    ] ──► Syncs Task Outcome to Tier 2 Store
                                │
                                ▼
 [ Finally: Lock Release & Cleanup  ] ──► Releases Concurrency Locks
                                │
                                ▼
                       EXECUTION COMPLETE

1. **Token-Dense Pointers**: The Orchestrator passes compact pointers (`task_id`, `project_name`).
2. **On-Demand Loading**: Agents inspect context on demand via `file.read("task_memory.md")` or `file.read("project_memory.md")`.
3. **80% Token Footprint Reduction**: Execution cycles run up to 4x faster with drastically reduced API costs and zero LLM context saturation.

---

## 🛡️ The 12-Step Chokepoint Action Gateway

Every mutating action in NAVA must pass sequentially through the 12-step `ActionGateway` chokepoint ([`src/nava/gateway/pipeline.py`](file:///c:/Users/aakhi/Desktop/Nava/src/nava/gateway/pipeline.py)):

                    INCOMING MUTATION REQUEST
                                │
                                ▼
 [ Step 1: Authentication & Lineage ] ──► Validates UUID & Active TTL
                                │
                                ▼
 [ Step 2: Policy Engine (ALLOW)   ] ──► Checks Static Rules & Security Switches
                                │
                                ▼
 [ Step 3: Additive Risk Engine     ] ──► Computes Additive Risk Score
                                │
                                ▼
 [ Step 4: Task Budget Engine       ] ──► Verifies Tokens, Steps & Depth
                                │
                                ▼
 [ Step 5: Concurrency Lock Manager ] ──► Acquires Shared/Exclusive Locks
                                │
                                ▼
 [ Step 6: HITL Approval Gate       ] ──► Triggers User Prompt if HIGH Risk
                                │
                                ▼
 [ Step 7: State Observer Snapshot  ] ──► Captures Pre-Execution File Hash
                                │
                                ▼
 [ Step 8: Execution Sandbox        ] ──► Dispatches Tool Locally or via MCP
                                │
                                ▼
 [ Step 9: Post-State Verification  ] ──► Validates Size, Path & Integrity
                                │
                                ▼
 [ Step 10: Audit Receipt Ledger    ] ──► Emits Signed JSON Receipt
                                │
                                ▼
 [ Step 11: Teardown & Lock Release ] ──► Releases Concurrency Locks
                                │
                                ▼
 [ Step 12: Episodic Memory Sync    ] ──► Syncs Task Outcome to Tier 2 Store
                                │
                                ▼
                       EXECUTION COMPLETE

---

## 🗄️ Four-Tier Memory Hierarchy & AI Twin

┌────────────────────────────────────────────────────────────────────────┐ │ 4-TIER MEMORY HIERARCHY │ ├────────────────────────────────────────────────────────────────────────┤ │ Tier 1: Working Memory │ Ephemeral task-scoped scratchpad │ │ Tier 2: Episodic Memory │ Append-only task receipts & execution logs│ │ Tier 3: Semantic Memory │ Chunked knowledge graph & RAG embeddings │ │ Tier 4: Profile Memory │ AI Twin verified facts & user preferences │ └────────────────────────────────────────────────────────────────────────┘

* **Profile Trust Escalation Gate (Invariant #20)**: External content (scraped web pages, downloaded documents, LLM inferences) can never silently write or upgrade memories to `VERIFIED` status in Tier 4 without explicit human confirmation.
* **Conflict Flagging**: Contradictory observations are tagged with `CONFLICT_DETECTED` and routed for user clarification.

---

## ⚖️ The 21 Certified System Invariants

NAVA mathematically guarantees 21 core operating system invariants:

1. **Mutation Gate Chokepoint**: 100% of state mutations must pass through the 12-step Action Gateway.
2. **Append-Only Audit Ledger**: `nava_audit.jsonl` is strictly append-only; past records cannot be modified or truncated.
3. **Receipt Immutability**: Cryptographic execution receipts are immutable once written.
4. **Root Ceiling Enforcement**: Dynamic subagents cannot exceed the root security ceiling in `nava.yaml`.
5. **Non-Increasing Permission Scoping**: $\text{Child Scope} = \text{Parent Scope} \cap \text{Requested Scope} \cap \text{Policy Allowed Scope}$.
6. **Maximum Spawn Depth Bound**: Dynamic agent spawn trees are strictly limited to $\text{depth} \le 10$.
7. **Runaway Loop Bound**: Maximum 3 retries on identical failure state; 4th identical failure halts execution.
8. **Short-Lived Credential Isolation**: Scoped credentials have a 5-minute TTL; raw tokens are isolated from agent context.
9. **Write-Exclusive Locking**: Exclusive write locks block concurrent read and write operations on the same resource.
10. **Shared-Read Concurrency**: Multiple subagents can acquire non-conflicting shared read locks concurrently.
11. **Automatic Reversible Rollback**: Tool failures on reversible operations trigger automatic pre-snapshot state restoration.
12. **Irreversible Compensation Routing**: Non-reversible failures route to `CompensationEngine` for compensation workflows.
13. **Bounded Cleanup Budget**: Rollback and compensation routines execute under a strict resource ceiling ($\le 5$ steps).
14. **HITL Escalation Gate**: Operations returning policy outcome `APPROVAL` strictly mandate a signed user approval record.
15. **Critical Risk Hard-Block**: Tools scoring in the `CRITICAL` risk tier are blocked from automated execution.
16. **Deterministic Resource Teardown**: Agent termination releases locks, revokes temporary credentials, and sets `TERMINATED` status.
17. **Skill Hash-Locking**: Modifying `SKILL.md` on disk triggers an `UNTRUSTED_MODIFIED` state, halting execution until re-hashed.
18. **Out-of-Band Emergency Kill Switch**: Invoking the kill switch immediately halts running threads, revokes credentials, and cancels approvals.
19. **Untrusted Delimiter Boundary**: External untrusted content is strictly wrapped in `<untrusted_content>` tags with tag escaping.
20. **Profile Trust Escalation Gate**: Inferred facts cannot promote themselves to `VERIFIED` tier without explicit user confirmation.
21. **Scope Alignment Invariant**: $\text{Agent Permission} \supseteq \text{Credential Scope} \supseteq \text{Tool Scope}$.

---

## ⚙️ Configuration & User-Configurable Security Switches

Configured in [`nava.yaml`](file:///c:/Users/aakhi/Desktop/Nava/nava.yaml):

```yaml
# Global Execution & Resource Budgets
budget:
  max_agents: 50
  max_depth: 10
  max_steps: 1000
  max_tokens: 1000000

# User-Configurable Security Feature Switches (Section 13 & 26)
security_switches:
  enable_terminal_execution: true    # Set to false to disable all shell/terminal execution
  enable_docker_sandboxing: true     # Set to false to disable ephemeral Docker container creation
  enable_desktop_gui_control: true   # Set to false to make ComputerAgent read-only (screenshots only)
  enable_browser_automation: true    # Set to false to disable Playwright web navigation & form automation
  enable_code_mutation: true         # Set to false to make CodingAgent read-only
  enable_external_integrations: true # Set to false to block external web MCPs, Gmail, and GitHub integrations
  enable_deep_audit_gates: true      # Set to false to bypass sequential thinking & AST security scanners
  enforce_codebase_isolation: true   # Set to false to disable strict isolation of NAVA's internal framework files

# Model Context Protocol (MCP) Ecosystem & Specialized Agent Servers
# (Set enabled: false on any server to completely disable and unregister it)
mcp_servers:
  context7:
    enabled: true
    command: "npx"
    args: ["-y", "@context7/mcp-server@latest"]
    assigned_roles: ["CodingAgent"]
    trust_state: "TRUSTED"
  
  superpowers:
    enabled: true
    command: "uvx"
    args: ["mcp-superpowers-code@latest"]
    assigned_roles: ["CodingAgent"]
    trust_state: "TRUSTED"

  git:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-git@latest"]
    assigned_roles: ["CodingAgent", "TerminalAgent"]
    trust_state: "TRUSTED"

  fetch:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-fetch@latest"]
    assigned_roles: ["ResearchAgent"]
    trust_state: "TRUSTED"

  brave-search:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-brave-search@latest"]
    assigned_roles: ["ResearchAgent"]
    trust_state: "TRUSTED"

  arxiv:
    enabled: true
    command: "uvx"
    args: ["mcp-server-arxiv@latest"]
    assigned_roles: ["ResearchAgent"]
    trust_state: "TRUSTED"

  sqlite:
    enabled: true
    command: "uvx"
    args: ["mcp-server-sqlite@latest"]
    assigned_roles: ["DataAgent"]
    trust_state: "TRUSTED"

  typst:
    enabled: true
    command: "uvx"
    args: ["typst-mcp-server@latest"]
    assigned_roles: ["DocumentAgent", "UniversalFileAgent"]
    trust_state: "TRUSTED"

  sequential-thinking:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking@latest"]
    assigned_roles: ["ReviewerAgent", "VerifierAgent"]
    trust_state: "TRUSTED"

  audit-scanner:
    enabled: true
    command: "uvx"
    args: ["nava-audit-mcp@latest"]
    assigned_roles: ["ReviewerAgent", "VerifierAgent"]
    trust_state: "TRUSTED"

  docker-sandbox:
    enabled: true
    command: "uvx"
    args: ["docker-sandbox-mcp@latest"]
    assigned_roles: ["TerminalAgent"]
    trust_state: "TRUSTED"

  playwright-browser:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-puppeteer@latest"]
    assigned_roles: ["BrowserAgent"]
    trust_state: "TRUSTED"

  desktop-automation:
    enabled: true
    command: "uvx"
    args: ["desktop-automation-mcp@latest"]
    assigned_roles: ["ComputerAgent"]
    trust_state: "TRUSTED"

  gmail:
    enabled: true
    command: "uvx"
    args: ["gmail-mcp-server@latest"]
    assigned_roles: ["EmailAgent"]
    trust_state: "TRUSTED"

  github:
    enabled: true
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github@latest"]
    assigned_roles: ["GitHubAgent"]
    trust_state: "TRUSTED"

---

💻 Interactive TUI Cowork Shell

Launch the command shell:

python nava_shell.py

Slash Commands:

• /mcp — Inspect active MCP servers, registered tools, trust status, and risk tiers.
• /mcp approve <server> <tool> — Approve new or modified MCP tool definitions into the trusted hash ledger.
• /twin — Inspect or update AI Twin persona facts (/twin set role Software Architect).
• /skills — Inspect loaded SKILL.md skills and their SHA-256 integrity hash status.
• /budget — View live task budget token, step, and agent consumption metrics.
• /kill — Trigger the out-of-band Emergency Kill Switch circuit breaker.
• tasks — View all past task memories.
• task resume <task_id> — Resume an existing task session with complete historical context.
• projects / project use <name> — Switch between isolated project workspaces.

---

📁 Repository Layout

.
├── .nava/                           # Project Workspace context ledger & AST checkpoints
├── memory/                          # Four-Tier persistent JSON memory stores
├── projects/                        # User project workspaces
├── tasks/                           # Isolated task sessions & deliverable artifacts
├── src/
│   └── nava/
│       ├── agents/
│       │   ├── factory.py           # AgentFactory with permission intersection
│       │   ├── planner.py           # GoalPlanner stage decomposition & tool assignment
│       │   ├── templates.py         # Static agent template catalog
│       │   └── runtime/             # LangGraph cyclic execution runtimes
│       ├── core/
│       │   ├── boot.py              # Bootstrapper & security switch ceiling filtering
│       │   ├── ledger.py            # Append-only audit ledger
│       │   ├── llm.py               # Frontier LLM gateway
│       │   ├── message_bus.py       # Inter-agent Pub/Sub broker
│       │   ├── sanitizer.py         # Prompt injection sanitizer
│       │   └── schemas.py           # Pydantic core schemas
│       ├── credentials/
│       │   ├── vault.py             # AES-256 credential vault
│       │   └── broker.py            # Scoped 5-minute credential broker
│       ├── gateway/
│       │   └── pipeline.py          # 12-step ActionGateway implementation
│       ├── governance/
│       │   ├── policy_engine.py     # Deterministic policy evaluation & security switches
│       │   ├── risk_engine.py       # Additive risk scoring
│       │   ├── budget_engine.py     # Token/step budgets & runaway loop detector
│       │   ├── lock_manager.py      # Read/write concurrency locks
│       │   ├── hitl_manager.py      # Human-in-the-Loop approval queues
│       │   ├── rollback_engine.py   # Reversible state restoration
│       │   ├── compensation_engine.py # Irreversible compensation routines
│       │   ├── dom_sanitizer.py     # DOM tripwire cleaner
│       │   └── state_observer.py    # Resource hash snapshotting
│       ├── memory/
│       │   ├── store.py             # Working, Episodic, Semantic, Profile memory stores
│       │   └── ai_twin.py           # AI Twin persona and fact manager
│       ├── prompts/                 # On-demand prompt templates
│       ├── skills/
│       │   ├── manager.py           # SKILL.md parsing & hash verification
│       │   └── promotion.py         # Dynamic skill promotion engine
│       ├── tools/
│       │   ├── executor.py          # LocalToolExecutor & codebase isolation sandbox
│       │   ├── registry.py          # ToolRegistry & schema definitions
│       │   ├── tool_manifest.py     # Complete tool catalog & MCP registration
│       │   ├── browser.py           # Playwright headless browser engine
│       │   ├── computer_engine.py   # OS desktop GUI perception & coordinate control
│       │   ├── terminal_engine.py   # TerminalEngine & DockerSandboxManager
│       │   ├── data_engine.py       # SQLite, SQL CSV & data profiling engine
│       │   ├── document_engine.py   # Typst Rust vector PDF engine
│       │   ├── audit_engine.py      # AST vulnerability & invariant verification engine
│       │   └── mcp_client.py        # StdioMCPClient & MCPClientManager
│       ├── ui/
│       │   └── cowork_tui.py        # Interactive terminal UI
│       ├── workspace/
│       │   ├── indexer.py           # AST symbol parser
│       │   └── project_manager.py   # Workspace context continuity engine
│       └── orchestrator.py          # End-to-end task orchestration kernel
├── tests/                           # Complete automated unit & integration test suites
│   ├── test_security_switches.py    # User security switches & MCP disabling tests
│   ├── test_browser_computer_mcp.py # Browser & desktop automation tests
│   ├── test_terminal_agent_mcp.py   # DevOps & Docker sandbox tests
│   ├── test_codebase_isolation.py   # Core codebase isolation sandbox tests
│   ├── test_21_invariants.py        # 21 System Invariants tests
│   ├── test_specialized_agents.py   # Static agent template tests
│   ├── test_project_workspace.py    # Workspace context tests
│   └── test_agent_message_bus.py    # Inter-agent Pub/Sub tests
├── nava.yaml                        # OS configuration, budgets & security policy
├── nava_shell.py                    # Interactive shell entrypoint
└── requirements.txt                 # Dependencies

---

🚀 Getting Started & Quickstart

1. Prerequisites

• Python 3.10 or higher
• Node.js / npx (for NPM MCP servers like @context7/mcp-server, @modelcontextprotocol/server-git)
• Python uv / uvx (for Python MCP servers like mcp-server-sqlite, typst-mcp-server)
• Google Gemini API Key (or local OpenAI-compatible LLM endpoint)

---

2. Installation Options

📦 Option A: Install from PyPI (Recommended)

You can install NAVA directly as a Python package or standalone CLI tool:

# Using standard pip
pip install nava-agent

# Or as an isolated global tool with pipx
pipx install nava-agent

# Install Playwright browser dependencies
playwright install chromium

🛠️ Option B: Install from Source (Developer Setup)

# Clone the repository
git clone https://github.com/your-org/nava.git
cd nava

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\activate

# Install in editable mode
pip install -e .
pip install -r requirements.txt

# Install Playwright browser binaries
playwright install chromium

---

3. Environment Configuration

Set your Gemini API key in your environment or create a .env file:

# Windows PowerShell
$env:GEMINI_API_KEY="your_gemini_api_key_here"

# Linux / macOS
export GEMINI_API_KEY="your_gemini_api_key_here"

Or create a .env file in your workspace root:

GEMINI_API_KEY=your_gemini_api_key_here
NAVA_ENV=development

---

4. Launching the Operating System

If installed via PyPI/pipx, launch from any directory using the global nava command:

nava

Or run the interactive shell directly from the repository:

python nava_shell.py

---

🧪 Automated Verification & Test Suite

Run the full automated test suite:

# 1. Verify User Security Switches & MCP Dynamic Disabling
python -m unittest tests/test_security_switches.py -v

# 2. Verify Browser & Desktop Computer Use MCP Suite
python -m unittest tests/test_browser_computer_mcp.py -v

# 3. Verify Terminal DevOps & Docker Sandboxing Suite
python -m unittest tests/test_terminal_agent_mcp.py -v

# 4. Verify Core Codebase Isolation Invariant
python -m unittest tests/test_codebase_isolation.py -v

# 5. Verify all 21 Certified System Invariants
python -m unittest tests/test_21_invariants.py -v

# 6. Verify Specialized Agent Templates
python -m unittest tests/test_specialized_agents.py -v

# 7. Verify Workspace Memory & AST Indexer
python -m unittest tests/test_project_workspace.py -v

# 8. Verify Inter-Agent Message Bus & Peer Review
python -m unittest tests/test_agent_message_bus.py -v

---

📄 License

Apache 2.0 License. See LICENSE for details.