Files/ComputerAssignments/CA2/AGENT.html

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="utf-8">
<title>AGENT</title>
<style>

body { font-family: Tahoma, 'Segoe UI', sans-serif; line-height: 2.0; font-size: 11pt; color: #0f172a; padding: 30px; background-color: #ffffff; }
h1 { color: #1e1b4b; border-bottom: 3px solid #4f46e5; padding-bottom: 10px; font-size: 22pt; margin-top: 30px; }
h2 { color: #1e293b; background-color: #f1f5f9; border-right: 5px solid #3b82f6; padding: 8px 12px; font-size: 16pt; margin-top: 25px; }
h3 { color: #2563eb; font-size: 13pt; margin-top: 20px; }
p { text-align: justify; margin-bottom: 15px; }
pre { background-color: #0f172a; color: #f8fafc; padding: 15px; border-radius: 6px; font-family: Courier, monospace; font-size: 10pt; overflow-x: auto; }
code { background-color: #f1f5f9; color: #0f172a; padding: 2px 5px; border-radius: 4px; font-family: Courier, monospace; }
table { border-collapse: collapse; width: 100%; margin: 20px 0; }
th, td { border: 1px solid #cbd5e1; padding: 10px; text-align: right; }
th { background-color: #f1f5f9; }
ul, ol { padding-right: 25px; }

</style>
</head>
<body>
<div class="container">
<h1>🤖 AirMouse Pro – Master Agent Specification (<code>AGENT.md</code>)</h1>
<p>Welcome to the definitive architecture, design, and operating manual for the <strong>AirMouse Pro</strong> Cyber-Physical System (CPS CA2 Assignment). </p>
<p>This document serves as the primary reference for AI Agents, developers, and evaluators interacting with the AirMouse ecosystem.</p>
<hr />
<h2>🏛️ 1. Executive System Overview</h2>
<p>AirMouse Pro is an end-to-end, ultra-low latency wireless air-mouse system. It transforms an Android smartphone into a high-precision 3D spatial cursor controller and gesture input device.</p>
<pre><code class="language-mermaid">graph TD
    A[&quot;Android App (Kotlin)&lt;br&gt;code/android/&quot;] --&gt;|TCP 9090 / UDP 9093| B[&quot;Go PC Server&lt;br&gt;code/pc/airmouse_mcp_go/&quot;]
    A --&gt;|Trace Markers| P[&quot;Perfetto Tracing&lt;br&gt;trace_file.perfetto-trace&quot;]
    B --&gt;|OS Cursor Events| C[&quot;Host OS Desktop&quot;]
    D[&quot;Python MCP Server (444 Tools)&lt;br&gt;airmouse_server_mcp.py&quot;] --&gt;|Admin REST 8081| B
    D --&gt;|ADB Automation| A
    E[&quot;Antigravity AI Agent&lt;br&gt;.agents/ Workspace&quot;] --&gt;|FastMCP / CLI| D
</code></pre>
<h3>Key Subsystems:</h3>
<ol>
<li><strong>Android Client (<code>code/android/</code>)</strong>: Pure Kotlin IMU reader, 3-step calibration manager, Madgwick AHRS filter ($\beta=0.041$), gesture detection, and line-delimited JSON TCP socket client.</li>
<li><strong>Go Desktop Backend (<code>code/pc/airmouse_mcp_go/</code>)</strong>: High-performance multi-protocol server (TCP 9090, WebSocket 9091, UDP Discovery 9092, UDP Stream 9093, REST Admin 8081) with Kalman predictive blending and power-law cursor acceleration.</li>
<li><strong>Python MCP Server (<code>airmouse_server_mcp.py</code>)</strong>: Master 444-tool FastMCP server and CLI supporting an extended 5-lifecycle agent hook engine.</li>
<li><strong>Antigravity Workspace (<code>.agents/</code>)</strong>: AI configuration hub featuring 22 domain-specific skills, system rules, dynamic memory, workflows, and environment settings.</li>
</ol>
<hr />
<h2>🧮 2. Mathematical Models &amp; Sensor Fusion</h2>
<h3>2.1 Madgwick AHRS Filter ($\beta = 0.041$)</h3>
<p>The orientation orientation quaternion $q = [q_1, q_2, q_3, q_4]^T$ is computed continuously using gradient descent optimization to fuse gyroscope ($\mathbf{\omega}$ in $\text{rad/s}$), accelerometer ($\mathbf{a}$ in $\text{m/s}^2$), and magnetometer ($\mathbf{m}$ in $\mu\text{T}$) inputs:</p>
<p>$$\dot{q} = \frac{1}{2} q \otimes \mathbf{\omega} - \beta \frac{\nabla f}{|\nabla f|}$$</p>
<ul>
<li><strong>Gyroscope Units</strong>: Standard Android $\text{rad/s}$ (never converted to degrees prior to filter update).</li>
<li><strong>Gain Parameter</strong>: Fixed at $\beta = 0.041$ for optimal balance between gyro drift rejection and dynamic response.</li>
</ul>
<h3>2.2 Quaternion to Euler Angles Conversion</h3>
<p>To translate orientation into screen space coordinates:</p>
<p>$$\begin{aligned}
\text{Roll } (\phi) &amp;= \operatorname{atan2}(2(q_1 q_2 + q_3 q_4), 1 - 2(q_2^2 + q_3^2)) \
\text{Pitch } (\theta) &amp;= \arcsin(2(q_1 q_3 - q_4 q_2)) \
\text{Yaw } (\psi) &amp;= \operatorname{atan2}(2(q_1 q_4 + q_2 q_3), 1 - 2(q_3^2 + q_4^2))
\end{aligned}$$</p>
<hr />
<h2>🎯 3. 3-Step Sensor Calibration Protocol</h2>
<table>
<thead>
<tr>
<th>Calibration Step</th>
<th>Sensor Target</th>
<th>Procedure</th>
<th>Mathematical Model</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Step 1: Gyroscope</strong></td>
<td>Gyro Bias Vector</td>
<td>Place phone on flat, vibration-free surface; collect <strong>100 stationary samples</strong>.</td>
<td>$\mathbf{b}<em>g = \frac{1}{100} \sum</em>{i=1}^{100} \mathbf{\omega}_i$</td>
</tr>
<tr>
<td><strong>Step 2: Magnetometer</strong></td>
<td>Hard/Soft-Iron Offsets</td>
<td>Perform figure-8 motion in 3D space; collect <strong>200 samples</strong>.</td>
<td>$\mathbf{V}<em>{\text{hard}} = \frac{\mathbf{m}</em>{\max} + \mathbf{m}<em>{\min}}{2}, \quad \mathbf{S}</em>{\text{soft}} = \frac{\text{avg_range}}{\mathbf{m}<em>{\max} - \mathbf{m}</em>{\min}}$</td>
</tr>
<tr>
<td><strong>Step 3: Accelerometer</strong></td>
<td>Scale &amp; Zero-g Bias</td>
<td>Place phone in 6 static orientations (Flat Up/Down, Left, Right, Top, Bottom).</td>
<td>Least-Squares Optimization to enforce $|\mathbf{a}| = 9.81 \text{ m/s}^2$</td>
</tr>
</tbody>
</table>
<hr />
<h2>🖐️ 4. Motion Gesture Detection Engine</h2>
<ul>
<li><strong>Click (Left Click)</strong>: Gyroscope Y-axis angular velocity $&gt; 8.0 \text{ rad/s}$ with a $300\text{ ms}$ cooldown.</li>
<li><strong>Double Click</strong>: Second left-click gesture detected within $400\text{ ms}$ of the first.</li>
<li><strong>Scroll Movement</strong>: Accelerometer Y-axis acceleration $&gt; 8.0 \text{ m/s}^2$ with a $2.0 \text{ m/s}^2$ debounce and $100\text{ ms}$ cooldown.</li>
<li><strong>Right Click</strong>: Roll tilt angle $&gt; 45^\circ$ held continuously for $\ge 500\text{ ms}$.</li>
</ul>
<hr />
<h2>📡 5. Network Protocol &amp; ACK Specification</h2>
<p>Messages are formatted as newline-delimited JSON (<code>\n</code>) transmitted over TCP port 9090 or UDP stream 9093.</p>
<h3>5.1 Packet Types &amp; Schemas</h3>
<ul>
<li><code>hello</code>: Client registration handshake (<code>{"type":"hello","device_name":"Pixel 8","version":"2.0"}</code>).</li>
<li><code>move</code>: Continuous delta orientation stream (<code>{"type":"move","dx":12.5,"dy":-4.2}</code>).</li>
<li><code>click</code>: Left-click request (<code>{"type":"click","id":"req_101"}</code>).</li>
<li><code>scroll</code>: Vertical scroll command (<code>{"type":"scroll","id":"req_102","delta":-3}</code>).</li>
<li><code>ack</code>: Server acknowledgment (<code>{"type":"ack","id":"req_101"}</code>).</li>
</ul>
<h3>5.2 Reliable Retransmission Logic</h3>
<p>For <code>click</code>, <code>scroll</code>, and <code>control</code> message types:
- Client starts a <strong>500 ms countdown timer</strong> upon sending.
- If no matching <code>ack</code> is received within $500\text{ ms}$, the packet is retransmitted (maximum <strong>3 retries</strong> before declaring a dropped connection).</p>
<hr />
<h2>🪝 6. Extended 5-Lifecycle Agent Hook Engine</h2>
<p>The MCP server CLI &amp; stdio interface includes an embedded hook engine managing 5 distinct lifecycle events:</p>
<ol>
<li><strong><code>pretool</code></strong> (PreToolUse): Executed immediately before a specific tool runs.</li>
<li><strong><code>posttool</code></strong> (PostToolUse): Executed immediately after a specific tool returns.</li>
<li><strong><code>preinvoke</code></strong> (PreInvocation): Executed once at the start of an agent invocation request.</li>
<li><strong><code>postinvoke</code></strong> (PostInvocation): Executed once after the full invocation completes.</li>
<li>
<p><strong><code>stop</code></strong> (Stop): Graceful shutdown hook executed via signal handlers (<code>SIGINT</code>/<code>SIGTERM</code>) or <code>atexit</code>.</p>
</li>
<li>
<p><strong>Configuration File</strong>: <code>~/.gemini/config/hooks.json</code></p>
</li>
<li><strong>Audit Log File</strong>: <code>~/.gemini/logs/hooks.log</code></li>
<li><strong>Environment Injections</strong>: <code>HOOK_TYPE</code>, <code>TOOL_NAME</code>, <code>ARGS</code>, <code>RESULT</code>.</li>
</ol>
<hr />
<h2>🧠 7. Antigravity Agent Workspace Layout (<code>.agents/</code>)</h2>
<p>The workspace <code>.agents/</code> directory provides workspace-level context to Google Antigravity:</p>
<pre><code>.agents/
├── .env                    # Environment variables (AIRMOUSE_PROJECT_ROOT, ports)
├── .env.template           # Template for required system environment variables
├── config.json             # Runtime configuration (gemini-3.1-pro, temp 0.15, max_tokens 16384)
├── instructions.md         # Master system instructions &amp; official documentation links
├── README.md               # Directory guide and documentation sitemap
├── memory/
│   ├── known_issues.json   # Knowledge graph of resolved bugs and tuning parameters
│   └── project_state.json  # Dynamic state tracking (builds, servers, devices)
├── rules/
│   └── airmouse-standards.md # Pure Kotlin/Go math rules &amp; 500ms ACK policies
├── workflows/
│   └── deploy.yml          # Multi-stage CI/CD pipeline script
└── skills/                 # 22 Domain Skill Folders with SKILL.md files
</code></pre>
<hr />
<h2>📈 8. Perfetto Trace Analysis (Questions Q1–Q11)</h2>
<p>The system includes Android <code>Trace.beginSection()</code> / <code>endSection()</code> markers:
- <code>AirMouseApp.Sensors.sensor_read</code>
- <code>AirMouseApp.Filter.complementary</code>
- <code>AirMouseApp.Filter.compute_delta</code>
- <code>AirMouseApp.Communication.send</code></p>
<h3>Metric Summary:</h3>
<ul>
<li><strong>Q1 (End-to-End Motion Latency)</strong>: $14.2\text{ ms}$ average latency from sensor read to TCP send.</li>
<li><strong>Q2 (Filter Execution Time)</strong>: $0.48\text{ ms}$ per Madgwick iteration.</li>
<li><strong>Q3 (Network Retransmission Overhead)</strong>: $&lt; 0.1\%$ packet loss under 5GHz Wi-Fi.</li>
<li><strong>Q4–Q11</strong>: Full metric queries documented in <a href="file:///Users/tahamajs/Documents/uni/CPS/Files/ComputerAssignments/CA2/Gozarish_Perfetto_CA2.md"><code>Gozarish_Perfetto_CA2.md</code></a> and <a href="file:///Users/tahamajs/Documents/uni/CPS/Files/ComputerAssignments/CA2/code/pc/perfetto_queries.sql"><code>code/pc/perfetto_queries.sql</code></a>.</li>
</ul>
<hr />
<h2>🌐 9. Official Google Antigravity Documentation Sitemap</h2>
<ul>
<li>🏠 <strong>Main Documentation Home</strong>: https://antigravity.google/docs</li>
<li>⚡ <strong>Skills System</strong>: https://antigravity.google/docs/skills</li>
<li>📜 <strong>Rules System</strong>: https://antigravity.google/docs/rules</li>
<li>🪝 <strong>Hooks System</strong>: https://antigravity.google/docs/hooks</li>
<li>🧩 <strong>Plugins Registry</strong>: https://antigravity.google/docs/plugins</li>
<li>🏎️ <strong>Sidecars</strong>: https://antigravity.google/docs/sidecars</li>
<li>🔌 <strong>Model Context Protocol (MCP)</strong>: https://antigravity.google/docs/mcp</li>
<li>🌐 <strong>Browser Automation &amp; Testing</strong>: https://antigravity.google/docs/browser</li>
<li>🛡️ <strong>Agent Permissions &amp; Security</strong>: https://antigravity.google/docs/agent-permissions</li>
<li>📜 <strong>Changelog &amp; Release Notes</strong>: https://antigravity.google/changelog</li>
<li>🆘 <strong>Troubleshooting &amp; Support</strong>: https://antigravity.google/support</li>
</ul>
</div>
</body>
</html>