Buckets:

tahamajs
/

CPS

Files

xet

tahamajs/CPS / Files /ComputerAssignments /CA2 /AGENTS.md

tahamajs

about 1 month ago

preview code

download

raw

20.5 kB

AirMouse Pro — Master Agent & System Guide (`AGENTS.md`)

Workspace Path: ~/Documents/uni/CPS/Files/ComputerAssignments/CA2
Project Name: AirMouse Pro (CPS Computer Assignment 2)
Purpose: Comprehensive system architecture, tool reference, workspace configuration, hook engine guide, and workflow specification for AI Agents and Developers.

1. Project Overview

AirMouse Pro is a high-performance Cyber-Physical System (CPS) that transforms an Android smartphone into a wireless 3D air-mouse and spatial controller. The system consists of four primary subsystems:

Android Client (code/android/): Pure Kotlin app package (com.airmouse) implementing IMU sensor reading, 3-step calibration, Madgwick AHRS sensor fusion ($\beta=0.041$), gesture detection, visual status indicators (green square with yellow click flash), Perfetto trace markers, and TCP newline-delimited JSON streaming.
Go Desktop Server (code/pc/airmouse_mcp_go/): High-throughput multi-protocol native server (TCP 9090, WebSocket 9091, UDP Discovery 9092, UDP Stream 9093, REST Admin 8081). Handles OS cursor movement with Kalman predictive blending, power-law acceleration, and 500ms ACK retransmissions.
Python MCP Server (airmouse_server_mcp.py): AI-Agent bridge built with FastMCP featuring 444 total tools for building, testing, ADB automation, trace analysis, PyAutoGUI control, and dynamic server administration across CLI and stdio modes.
Antigravity Workspace (.agents/): AI workspace configuration hub featuring 22 domain-specific skills, quality rules, system instructions, dynamic state memory, workflows, and environment variables.

2. Directory Layout

~/Documents/uni/CPS/Files/ComputerAssignments/CA2/
├── AGENTS.md                          # Master Agent & System Guide
├── AGENT.md                           # Architecture blueprint & math models
├── HOOKS.md                           # CLI & stdio 5-lifecycle hook system documentation
├── FINAL_PROJECT_DOCUMENTATION.md     # Executive project documentation report
├── FULL_TEST_SUITE_RESULTS.md         # Consolidated unit/integration test matrix
├── Gozarish_Perfetto_CA2.md           # Perfetto trace latency analysis (Q1–Q11)
├── PROTOCOL_COMPLIANCE.md             # Network protocol specification
├── README.md                          # Project repository guide
├── CPS-CA2-00000.zip                  # Final submission archive
├── airmouse_server_mcp.py             # 444-tool FastMCP Python Server & CLI
├── create_plugins.py                  # Plugin registry generator script
├── code/
│   ├── android/                       # Android Studio Gradle Project (Kotlin)
│   │   ├── app/src/main/java/com/airmouse/
│   │   │   ├── sensors/               # MadgwickAHRS.kt, CalibrationHelper.kt, MotionDetector.kt
│   │   │   ├── network/               # ConnectionManager.kt (TCP/UDP/ACK)
│   │   │   └── ui/                    # OnboardingActivity, CalibrationActivity, HomeFragment
│   │   └── gradlew                    # Gradle build wrapper
│   └── pc/                            # Desktop Backend & Testing Tools
│       ├── airmouse_mcp_go/           # Go Native Server source & main.go
│       ├── airmouse-mcp-go            # Compiled CGO-free Go binary
│       ├── test_pc_server.py          # Standalone TCP/ACK unit tests
│       ├── test_e2e.py                # End-to-end integration test runner
│       └── perfetto_queries.sql       # Perfetto trace metrics SQL queries
└── .agents/                           # Antigravity Workspace Hub
    ├── .env                           # Environment variables
    ├── .env.template                  # Environment template
    ├── config.json                    # Agent runtime configuration
    ├── instructions.md                # System instructions & docs links
    ├── README.md                      # Workspace hub README
    ├── memory/
    │   ├── known_issues.json          # Resolved bugs & tuning memory
    │   └── project_state.json         # Dynamic build & server state
    ├── rules/
    │   └── airmouse-standards.md      # Development & quality standards
    ├── workflows/
    │   └── deploy.yml                 # Automation pipeline workflow
    └── skills/                        # 22 Domain-Specific Skill Modules
        ├── airmouse-sensor-fusion/    # SKILL.md
        ├── airmouse-network/          # SKILL.md
        ├── airmouse-testing/          # SKILL.md
        ├── airmouse-perfetto/         # SKILL.md
        ├── airmouse-build/            # SKILL.md
        ├── airmouse-calibration/      # SKILL.md
        ├── airmouse-gesture-detection/# SKILL.md
        ├── airmouse-mouse-control/    # SKILL.md
        ├── airmouse-ui-automation/    # SKILL.md
        ├── airmouse-voice-commands/   # SKILL.md
        ├── airmouse-game-profiles/    # SKILL.md
        ├── airmouse-go-server-admin/  # SKILL.md
        ├── airmouse-project-overview/ # SKILL.md
        ├── airmouse-documentation/    # SKILL.md
        ├── airmouse-troubleshooting/  # SKILL.md
        ├── airmouse-performance-optimization/ # SKILL.md
        ├── airmouse-security/         # SKILL.md
        ├── airmouse-deployment/       # SKILL.md
        ├── airmouse-advanced-sensors/ # SKILL.md
        ├── airmouse-protocol-analysis/# SKILL.md
        ├── airmouse-customisation/   # SKILL.md
        └── airmouse-code-quality/     # SKILL.md

3. Key Constants & Parameters

Parameter	Value	Subsystem	Description
`Madgwick Beta` ($\beta$)	`0.041`	Android Client	Fixed Madgwick AHRS filter gain parameter for optimal drift rejection.
`Gyro Units`	`rad/s`	Android Client	Raw angular velocity from Android `SensorManager` (no degree conversion).
`Gyro Click Threshold`	$> 8.0\text{ rad/s}$	Gesture Engine	Angular velocity on Y-axis required to trigger a left-click gesture ($300\text{ms}$ cooldown).
`Double Click Window`	$< 400\text{ ms}$	Gesture Engine	Maximum time window between two left clicks to trigger a double-click event.
`Accel Scroll Threshold`	$> 8.0\text{ m/s}^2$	Gesture Engine	Y-axis acceleration threshold for vertical scrolling ($2.0\text{ m/s}^2$ debounce, $100\text{ms}$ cooldown).
`Right Click Roll Tilt`	$> 45^\circ$	Gesture Engine	Roll tilt angle required for right-click activation (held for $\ge 500\text{ms}$).
`ACK Timeout`	`500 ms`	Networking	Maximum wait duration before retransmitting unacknowledged packets.
`ACK Retries`	`3`	Networking	Maximum retransmission retry limit for `click`, `scroll`, and `control` messages.
`TCP Port`	`9090`	Networking	Primary newline-delimited JSON streaming & command socket.
`WebSocket Port`	`9091`	Networking	Browser & Web app connection port.
`UDP Discovery Port`	`9092`	Networking	Broadcast port for auto-discovering PC servers on LAN.
`UDP Stream Port`	`9093`	Networking	High-frequency low-overhead orientation streaming port.
`REST Admin Port`	`8081`	Go Server	HTTP REST API port for live stats, device approval, and configuration.

4. Python MCP Server (`airmouse_server_mcp.py`)

The MCP server provides an AI-Agent bridge exposing 444 total tools across dual execution modes:

CLI Mode: python airmouse_server_mcp.py <tool_name> [args...]
MCP Stdio Mode: python airmouse_server_mcp.py (FastMCP stdio JSON-RPC interface)

Primary Tool Categories & Representative Tool Examples:

Build: build_android_debug, build_android_release, clean_android_build, build_go_server, clean_go_build
Testing: test_android_unit, test_go_server, test_live_protocols, test_full_system, run_full_protocol_validation, generate_full_test_report
ADB & Device Control: list_adb_devices, install_apk, uninstall_apk, launch_android_app, clear_app_data, dump_logcat, screenshot_device, pull_traces
Server Management: start_server, stop_server, start_go_server, stop_go_server, restart_server, server_status, view_server_logs
Perfetto Trace Analysis: analyze_perfetto_trace, capture_perfetto_trace, get_perfetto_metric, run_perfetto_analyzer, answer_perfetto_q1 through answer_perfetto_q11
Documentation: generate_master_documentation, generate_test_report, generate_perfetto_report, generate_project_tree, generate_changelog, generate_demo_script, generate_submission_zip
Mouse Control (PyAutoGUI): move_mouse, move_mouse_to, left_click, right_click, double_click, scroll_up, scroll_down, drag_mouse, type_text, press_key, hotkey
Calibration Suite: calibration_check_status, calibration_reset, calibration_launch_gyro_step, calibration_launch_mag_step, calibration_launch_accel_step, calibration_validate_gyro_bias, calibration_validate_mag_offset, calibration_validate_accel_offset, calibration_compute_accel_6point
Go Server Admin: go_get_stats, go_get_devices, go_set_sensitivity, go_set_smoothing, go_set_acceleration, go_set_predictive, go_set_jitter_compensation, go_set_humanizer, go_set_gesture_thresholds, go_set_gesture_mapping
Gesture Simulation: test_gesture_click, test_gesture_double_click, test_gesture_right_click, test_gesture_scroll, test_gesture_move, gesture_thumbs_up, gesture_swipe_left
Utilities: search_files, read_file, list_directory, full_ci_pipeline, full_deploy, health_check, system_info, backup_project, clean_workspace, count_lines_of_code

5. Antigravity Workspace Configuration (`.agents/`)

5.1 The 22 Workspace Skills Index

#	Skill Identifier	Description	Main Prompt Triggers
1	`airmouse-sensor-fusion`	Madgwick AHRS filter math, quaternions, Euler angle conversions, $\beta=0.041$ tuning.	`sensor fusion`, `madgwick`, `quaternion`
2	`airmouse-network`	TCP (9090), WebSocket (9091), UDP Discovery (9092/9093), 500ms ACK retransmissions.	`network`, `tcp`, `websocket`, `ack`
3	`airmouse-testing`	Unit, integration, live, and Mockito/Espresso test suites for Android, Go, and Python.	`test`, `unittest`, `robolectric`, `espresso`
4	`airmouse-perfetto`	Perfetto trace capture, metrics queries, and answers for questions Q1 through Q11.	`perfetto`, `trace`, `q1`, `latency`
5	`airmouse-build`	Android Gradle compilation, Go server CGO-free build, dependency resolution.	`build`, `compile`, `apk`, `gradle`
6	`airmouse-calibration`	3-step calibration (Gyro bias, Mag figure-8, Accel 6-position least-squares).	`calibrate`, `gyro bias`, `mag offset`
7	`airmouse-gesture-detection`	Gyro Y-axis click ($>8.0\text{ rad/s}$), Accel Y scroll ($>8.0\text{ m/s}^2$), Roll tilt right-click ($>45^\circ$).	`gesture`, `click`, `scroll`, `right-click`
8	`airmouse-mouse-control`	PyAutoGUI and native server-side cursor movement, click, drag, and hotkey automation.	`mouse`, `move`, `pyautogui`, `cursor`
9	`airmouse-ui-automation`	ADB screen taps, swipes, input events, developer options, and layout inspection.	`adb`, `tap`, `swipe`, `logcat`
10	`airmouse-voice-commands`	Speech recognition mapping, text-to-speech simulation, and voice control macros.	`voice`, `speech`, `command`
11	`airmouse-game-profiles`	Gaming preset profiles (FPS, Racing, RPG) with custom sensitivity curves.	`game`, `profile`, `fps`, `racing`
12	`airmouse-go-server-admin`	Go server REST Admin API (Port 8081) for live parameters, stats, and device approvals.	`go server`, `admin api`, `stats`
13	`airmouse-project-overview`	High-level project architecture, folder layout, port assignments, and component maps.	`overview`, `architecture`, `ports`
14	`airmouse-documentation`	Report generation (`FINAL_PROJECT_DOCUMENTATION.md`), changelogs, and submission ZIP.	`docs`, `report`, `changelog`, `zip`
15	`airmouse-troubleshooting`	Error log diagnostics, ANR trace extraction, crash analysis, and ADB logcat parsing.	`error`, `crash`, `debug`, `anr`
16	`airmouse-performance-optimization`	CPU/Memory/Network tuning, sensor sampling rate adjustments, build flags.	`perf`, `optimize`, `cpu`, `memory`
17	`airmouse-security`	Authentication tokens, protocol validation, app permissions, and security hardening.	`security`, `permission`, `auth`
18	`airmouse-deployment`	End-to-end build $\rightarrow$ install $\rightarrow$ launch $\rightarrow$ connect deployment pipeline.	`deploy`, `install`, `launch`
19	`airmouse-advanced-sensors`	IMU sensor coordinate transformations, Allan variance, bias stability, CTS sensor tests.	`imu`, `allan variance`, `cts`
20	`airmouse-protocol-analysis`	Packet inspection, retransmission timing, network jitter, and latency breakdown.	`protocol`, `packet`, `latency`
21	`airmouse-customisation`	UI theme customisation, threshold adjustments, gesture re-mapping.	`theme`, `threshold`, `sensitivity`
22	`airmouse-code-quality`	Linting (`lint_android`, `lint_go`), static code analysis, code formatting.	`lint`, `format`, `static analysis`

5.2 Quality Rules (`rules/airmouse-standards.md`)

Pure Math Implementations: No external sensor fusion dependencies; pure Kotlin and pure Go math.
Strict 3-Step Calibration: Must enforce Gyro 100-sample, Mag 200-sample, Accel 6-position standards.
Perfetto Completeness: All 11 questions (Q1–Q11) must be answered with trace evidence prior to submission.
Race Detection: Go server tests must execute with -race flag enabled.
Pre-Commit CI: Always run full_ci_pipeline before committing code.
Doc Sync: Documentation files must be regenerated after code changes.

5.3 System Instructions (`instructions.md`)

Tool-First Policy: Prefer autonomous MCP tool calls over requesting manual user actions.
Skill Consultation: Consult .agents/skills/ for domain workflows.
Bilingual Support: Default to English, but respond fluently in Persian (Farsi) when addressed in Persian.
Destructive Confirmation: Always confirm before executing clean or force-stop commands.

5.4 Dynamic Memory & Config Files

memory/project_state.json: Tracks build status (android, go), calibration check state, Perfetto status, and active server process.
memory/known_issues.json: Long-term memory of resolved bugs (e.g. rad/s double conversion fix) and tuning constants.
config.json: {"model": "gemini-3.1-pro", "temperature": 0.15, "max_tokens": 16384, "strict_tool_use": true, "auto_load_skills": true}
.env & .env.template: Sets AIRMOUSE_PROJECT_ROOT, ANDROID_HOME, JAVA_HOME, GO_PATH.

6. Extended 5-Lifecycle Agent Hook Engine

Hooks are stored in ~/.gemini/config/hooks.json and executed synchronously by the embedded Python engine in airmouse_server_mcp.py.

6.1 The 5 Lifecycle Events

pretool (PreToolUse): Triggered before an individual tool call executes.
posttool (PostToolUse): Triggered after an individual tool call completes.
preinvoke (PreInvocation): Triggered once at the start of an agent invocation request.
postinvoke (PostInvocation): Triggered once after an invocation request completes.
stop (Stop): Triggered when the server exits gracefully (SIGINT, SIGTERM, atexit).

6.2 CLI Hook Management Commands

# List all configured hooks
python airmouse_server_mcp.py hooks list

# Add a pretool hook for a specific tool
python airmouse_server_mcp.py hooks add --tool move_mouse --type pretool --command "echo 'Moving mouse: \$dx, \$dy'"

# Add a global preinvoke hook
python airmouse_server_mcp.py hooks add --type preinvoke --command "echo 'Session starting' >> ~/.gemini/logs/hooks.log"

# Add a stop hook for process exit notification
python airmouse_server_mcp.py hooks add --type stop --command "osascript -e 'display notification \"Server stopping\" with title \"AirMouse\"'"

# Test / Remove / Clear
python airmouse_server_mcp.py hooks test --tool move_mouse --type pretool --args '{"dx": 10, "dy": 20}'
python airmouse_server_mcp.py hooks remove 1
python airmouse_server_mcp.py hooks clear

7. Common Copy-Paste Workflows

Workflow 1: Complete Build & CI Pipeline

python airmouse_server_mcp.py full_ci_pipeline

Workflow 2: Execute 3-Step Calibration Sequence

python airmouse_server_mcp.py calibration_launch_gyro_step
python airmouse_server_mcp.py calibration_launch_mag_step
python airmouse_server_mcp.py calibration_launch_accel_step
python airmouse_server_mcp.py calibration_check_status

Workflow 3: Perfetto Trace Capture & Q1–Q11 Analysis

python airmouse_server_mcp.py capture_perfetto_trace duration="10s"
python airmouse_server_mcp.py run_perfetto_analyzer
python airmouse_server_mcp.py generate_perfetto_report

Workflow 4: Full Protocol Validation & Documentation Sync

python airmouse_server_mcp.py run_full_protocol_validation
python airmouse_server_mcp.py generate_master_documentation
python airmouse_server_mcp.py generate_test_report

Workflow 5: Generate Clean Final Submission ZIP

python airmouse_server_mcp.py generate_submission_zip

8. Environment Variables

Variable	Default Value / Path	Description
`AIRMOUSE_PROJECT_ROOT`	`~/Documents/uni/CPS/Files/ComputerAssignments/CA2`	Absolute path to the AirMouse project root.
`ANDROID_HOME`	`/Users/tahamajs/Library/Android/sdk`	Path to Android SDK installation.
`JAVA_HOME`	`/Library/Java/JavaVirtualMachines/.../Contents/Home`	Path to JDK installation.
`GO_PATH`	`~/go`	Path to Go workspace directory.
`HOOK_TYPE`	Injected dynamically (`pretool`, `preinvoke`, etc.)	Current active hook lifecycle event.
`TOOL_NAME`	Injected dynamically (`move_mouse`, etc.)	Name of the tool currently executing.
`ARGS`	Injected dynamically (JSON string)	Tool input parameters.
`RESULT`	Injected dynamically (JSON string)	Tool execution result payload.

9. Official Google Antigravity Documentation Links

🏠 Main Documentation Home: https://antigravity.google/docs
⚡ Skills System: https://antigravity.google/docs/skills
📜 Rules System: https://antigravity.google/docs/rules
🪝 Hooks System: https://antigravity.google/docs/hooks
🧩 Plugins Registry: https://antigravity.google/docs/plugins
🏎️ Sidecars: https://antigravity.google/docs/sidecars
🔌 Model Context Protocol (MCP): https://antigravity.google/docs/mcp
🌐 Browser Automation & Testing: https://antigravity.google/docs/browser
🛡️ Agent Permissions & Security: https://antigravity.google/docs/agent-permissions
📜 Changelog & Release Notes: https://antigravity.google/changelog
🆘 Troubleshooting & Support: https://antigravity.google/support

10. Quick Reference Card

Goal / Action	Command / Method
Build Android Debug APK	`python airmouse_server_mcp.py build_android_debug`
Build Native Go Server	`python airmouse_server_mcp.py build_go_server`
Run Go Tests with Race Detector	`python airmouse_server_mcp.py test_go_with_race`
Run Standalone Python TCP Test	`python airmouse_server_mcp.py pc_run_test_pc_server`
Run E2E Integration Suite	`python airmouse_server_mcp.py pc_run_e2e_python_test`
List Installed Hooks	`python airmouse_server_mcp.py hooks list`
Reload Workspace Skills (TUI)	`/skill reload`
List Active Skills (TUI)	`/skill list`
Load Specific Skill (TUI)	`/skill load airmouse-sensor-fusion`
Generate Submission Archive	`python airmouse_server_mcp.py generate_submission_zip`

Status: The AirMouse Pro CA2 project is 100% complete, fully tested, documented, and ready for submission!

Xet Storage Details

Size:: 20.5 kB
Xet hash:: a48b374687808595ce7cf61c8802aaee2b93e228602d76115f3d1326d8675ad8

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

AirMouse Pro — Master Agent & System Guide (AGENTS.md)