@pixelkit-labs/cli 1.5.1 → 1.5.6

package/LICENSE

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2026 Traves Theberge
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2026 Traves Theberge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,69 +1,70 @@
-# @pixelkit-labs/cli
-
-Command-line diagnostics for [PixelKit](https://www.npmjs.com/package/@pixelkit-labs/sdk). Its only command,
-`pixelkit doctor`, answers "why is everything showing —?" before you file an issue.
-
-PixelKit hooks report `source: 'unavailable'` and render an em dash when a reading cannot be taken
-on real hardware. That is correct behaviour, but on the wrong device, without a development build,
-or without the native packages installed, every hook looks that way at once. `doctor` runs the
-checks a maintainer would run by hand.
-
-**Zero third-party dependencies.** It uses only Node's `child_process` and `util`.
-
-```bash
-npx @pixelkit-labs/cli doctor
-```
-
-or, installed as a dev dependency:
-
-```bash
-npm install --save-dev @pixelkit-labs/cli
-npx pixelkit doctor
-```
-
-## What it checks
-
-1. **adb on PATH and exactly one device connected** (`adb devices`). If several devices are
-   connected, they are listed and you are told to pass `--serial`.
-2. **The connected device's identity** — manufacturer, model, Android release, SDK int
-   (`adb shell getprop`). States plainly whether it is a Pixel, because most hooks report
-   `unavailable` otherwise.
-3. **Whether a PixelKit-based development build is installed** (`adb shell pm path <package>`),
-   keyed off `--package` (default `com.pixelkit.sdk`). Expo Go can never satisfy this: the Kotlin
-   Expo Modules (`@pixelkit-labs/native`, `@pixelkit-labs/mlkit`) must be compiled in.
-4. **Whether `@pixelkit-labs/native` and `@pixelkit-labs/mlkit` resolve from the current project**
-   (`require.resolve` from the working directory), and which hook groups are therefore available.
-   A missing `@pixelkit-labs/mlkit` is reported as informational, not a failure — it is the opt-in ML
-   Kit package.
-5. **Whether AICore is present on the device** (`adb shell pm list packages`, matched for
-   "aicore"), which Gemini Nano needs. Not-applicable on a non-Pixel.
-6. **Whether `adb reverse tcp:8081 tcp:8081` is set**, so a development client can reach Metro on
-   localhost.
-
-Each check is reported as `PASS`, `FAIL`, `N/A` or `UNKN` ("could not be determined" — the check
-itself could not be run, for example because adb is missing or the device went offline).
-`doctor` never guesses a result: an inconclusive check is reported as such, the same discipline
-PixelKit hooks use for `source: 'unavailable'`.
-
-## Options
-
-```
-pixelkit doctor [--package <id>] [--serial <serial>]
-
-  --package <id>   Application id of the installed PixelKit development build
-                    (default: com.pixelkit.sdk)
-  --serial <id>    adb serial to target when more than one device is connected
-  -h, --help        Show help
-```
-
-## Exit code
-
-`0` when every check passed or was not applicable. `1` when any check failed, or could not be
-determined at all.
-
-## Documentation
-
-[https://pixelkit-labs.github.io/pixelkit-docs/](https://pixelkit-labs.github.io/pixelkit-docs/) covers the hooks this command
-diagnoses: each one's inputs, outputs, and what `source: 'unavailable'` means for it.
-
-MIT
+# @pixelkit-labs/cli
+
+Command-line diagnostics and autonomous hardware agents for [PixelKit](https://www.npmjs.com/package/@pixelkit-labs/sdk).
+- `pixelkit doctor`: answers "why is everything showing —?" before you file an issue.
+- `pixelkit agent`: runs autonomous on-device hardware telemetry triage (CPU, battery, thermals, AICore) and queries the Google Gen AI hardware agent.
+
+PixelKit hooks report `source: 'unavailable'` and render an em dash when a reading cannot be taken
+on real hardware. That is correct behaviour, but on the wrong device, without a development build,
+or without the native packages installed, every hook looks that way at once. `doctor` and `agent`
+run the checks and diagnostics an expert systems engineer would run by hand.
+
+**Zero third-party dependencies.** It uses only Node's `child_process`, `util`, and native `fetch`.
+
+```bash
+# Verify environment readiness
+npx @pixelkit-labs/cli doctor
+
+# Run autonomous hardware diagnostic triage
+npx @pixelkit-labs/cli agent --diagnose
+
+# Query the hardware agent with custom diagnostic prompt
+npx @pixelkit-labs/cli agent --query "Check battery wear and thermal throttling headroom"
+```
+
+## What it checks
+
+1. **adb on PATH and exactly one device connected** (`adb devices`). If several devices are
+   connected, they are listed and you are told to pass `--serial`.
+2. **The connected device's identity** — manufacturer, model, Android release, SDK int
+   (`adb shell getprop`). States plainly whether it is a Pixel, because most hooks report
+   `unavailable` otherwise.
+3. **Whether a PixelKit-based development build is installed** (`adb shell pm path <package>`),
+   keyed off `--package` (default `com.pixelkit.sdk`). Expo Go can never satisfy this: the Kotlin
+   Expo Modules (`@pixelkit-labs/native`, `@pixelkit-labs/mlkit`) must be compiled in.
+4. **Whether `@pixelkit-labs/native` and `@pixelkit-labs/mlkit` resolve from the current project**
+   (`require.resolve` from the working directory), and which hook groups are therefore available.
+   A missing `@pixelkit-labs/mlkit` is reported as informational, not a failure — it is the opt-in ML
+   Kit package.
+5. **Whether AICore is present on the device** (`adb shell pm list packages`, matched for
+   "aicore"), which Gemini Nano needs. Not-applicable on a non-Pixel.
+6. **Whether `adb reverse tcp:8081 tcp:8081` is set**, so a development client can reach Metro on
+   localhost.
+
+Each check is reported as `PASS`, `FAIL`, `N/A` or `UNKN` ("could not be determined" — the check
+itself could not be run, for example because adb is missing or the device went offline).
+`doctor` never guesses a result: an inconclusive check is reported as such, the same discipline
+PixelKit hooks use for `source: 'unavailable'`.
+
+## Options
+
+```
+pixelkit doctor [--package <id>] [--serial <serial>]
+
+  --package <id>   Application id of the installed PixelKit development build
+                    (default: com.pixelkit.sdk)
+  --serial <id>    adb serial to target when more than one device is connected
+  -h, --help        Show help
+```
+
+## Exit code
+
+`0` when every check passed or was not applicable. `1` when any check failed, or could not be
+determined at all.
+
+## Documentation
+
+[https://pixelkit-labs.github.io/pixelkit-docs/](https://pixelkit-labs.github.io/pixelkit-docs/) covers the hooks this command
+diagnoses: each one's inputs, outputs, and what `source: 'unavailable'` means for it.
+
+MIT

package/build/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * @file packages/cli/index.ts
+ * @file index.ts
  * @description `pixelkit doctor`: the first and only command of `@pixelkit-labs/cli`. PixelKit hooks
  * report `source: 'unavailable'` and render an em dash when a reading cannot be taken on real
  * hardware; on the wrong device, without a development build, or without the native packages

package/build/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * @file packages/cli/index.ts
+ * @file index.ts
  * @description `pixelkit doctor`: the first and only command of `@pixelkit-labs/cli`. PixelKit hooks
  * report `source: 'unavailable'` and render an em dash when a reading cannot be taken on real
  * hardware; on the wrong device, without a development build, or without the native packages
@@ -351,6 +351,21 @@ function parseArgs(argv) {
         else if (arg.startsWith('--serial=')) {
             flags.serial = arg.slice('--serial='.length);
         }
+        else if (arg === '--diagnose') {
+            flags.diagnose = true;
+        }
+        else if (arg === '--query' || arg === '-q') {
+            flags.query = argv[++i];
+        }
+        else if (arg.startsWith('--query=')) {
+            flags.query = arg.slice('--query='.length);
+        }
+        else if (arg === '--model' || arg === '-m') {
+            flags.model = argv[++i];
+        }
+        else if (arg.startsWith('--model=')) {
+            flags.model = arg.slice('--model='.length);
+        }
         else if (arg === '--help' || arg === '-h') {
             flags.help = true;
         }
@@ -361,15 +376,23 @@ function parseArgs(argv) {
     return { command, flags };
 }
 function printUsage() {
-    console.log(`${ANSI.bold}pixelkit doctor${ANSI.reset} - diagnose why PixelKit hooks might report source: "unavailable"
-
-Usage:
-  pixelkit doctor [--package <id>] [--serial <serial>]
-
-Options:
-  --package <id>   Application id of the installed PixelKit development build (default: com.pixelkit.sdk)
-  --serial <id>    adb serial to target when more than one device is connected
-  -h, --help       Show this help
+    console.log(`${ANSI.bold}pixelkit${ANSI.reset} - developer tooling and diagnostics for Google Pixel hardware
+
+Usage:
+  pixelkit doctor [--package <id>] [--serial <serial>]
+  pixelkit agent [--diagnose] [--query <prompt>] [--model <model>] [--serial <serial>]
+
+Commands:
+  doctor           Diagnose why PixelKit hooks might report source: "unavailable"
+  agent            Run autonomous hardware diagnostics and query the device agent
+
+Options:
+  --diagnose       Run complete hardware diagnostic triage (CPU, battery, thermals, AICore)
+  --query, -q      Query the hardware agent with a specific diagnostic question
+  --model, -m      Gemini model for cloud reasoning (default: gemini-2.5-flash)
+  --package <id>   Application id of the installed PixelKit development build (default: com.pixelkit.sdk)
+  --serial <id>    adb serial to target when more than one device is connected
+  -h, --help       Show this help
 `);
 }
 function printResult(r) {
@@ -377,6 +400,172 @@ function printResult(r) {
     if (r.fix)
         console.log(`${ANSI.dim}         fix: ${r.fix}${ANSI.reset}`);
 }
+/**
+ * Runs the autonomous hardware agent diagnostic command.
+ */
+async function runHardwareAgent(flags) {
+    console.log(`${ANSI.bold}PixelKit Hardware Diagnostics Agent${ANSI.reset}\n`);
+    const step1 = await checkAdbAndDevice(flags.serial);
+    if (step1.result.status === 'fail' || !step1.serial) {
+        printResult(step1.result);
+        return 1;
+    }
+    const serial = step1.serial;
+    console.log(`${ANSI.dim}Collecting hardware telemetry from ${serial}...${ANSI.reset}`);
+    // 1. Device identity & SoC
+    const modelRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.product.model']);
+    const manufacturerRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.product.manufacturer']);
+    const releaseRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.build.version.release']);
+    const sdkRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.build.version.sdk']);
+    const socRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.soc.model']);
+    const platformRes = await runAdb(['-s', serial, 'shell', 'getprop', 'ro.board.platform']);
+    const model = modelRes.ok ? modelRes.stdout.trim() : 'Unknown';
+    const manufacturer = manufacturerRes.ok ? manufacturerRes.stdout.trim() : 'Unknown';
+    const release = releaseRes.ok ? releaseRes.stdout.trim() : 'Unknown';
+    const sdk = sdkRes.ok ? sdkRes.stdout.trim() : 'Unknown';
+    const soc = socRes.ok && socRes.stdout.trim() ? socRes.stdout.trim() : (platformRes.ok ? platformRes.stdout.trim() : 'Google Tensor');
+    // 2. Battery telemetry
+    const batteryRes = await runAdb(['-s', serial, 'shell', 'dumpsys', 'battery']);
+    let batteryLevel = 'N/A';
+    let batteryTemp = 'N/A';
+    let batteryVoltage = 'N/A';
+    let batteryStatus = 'N/A';
+    let batteryHealth = 'N/A';
+    if (batteryRes.ok) {
+        const lines = batteryRes.stdout.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('level:'))
+                batteryLevel = trimmed.split(':')[1].trim() + '%';
+            else if (trimmed.startsWith('temperature:')) {
+                const raw = parseFloat(trimmed.split(':')[1].trim());
+                batteryTemp = (raw / 10).toFixed(1) + '°C';
+            }
+            else if (trimmed.startsWith('voltage:')) {
+                const raw = parseFloat(trimmed.split(':')[1].trim());
+                batteryVoltage = (raw / 1000).toFixed(2) + 'V';
+            }
+            else if (trimmed.startsWith('status:')) {
+                const code = trimmed.split(':')[1].trim();
+                batteryStatus = code === '2' ? 'Charging' : code === '3' ? 'Discharging' : code === '5' ? 'Full' : 'Not Charging';
+            }
+            else if (trimmed.startsWith('health:')) {
+                const code = trimmed.split(':')[1].trim();
+                batteryHealth = code === '2' ? 'Good' : 'Degraded';
+            }
+        }
+    }
+    // 3. Thermal telemetry
+    const thermalRes = await runAdb(['-s', serial, 'shell', 'dumpsys', 'thermalservice']);
+    let thermalStatus = 'Normal (0)';
+    if (thermalRes.ok) {
+        const match = thermalRes.stdout.match(/mStatus=(\d+)/i) || thermalRes.stdout.match(/Current thermal status: (\d+)/i);
+        if (match) {
+            const code = parseInt(match[1], 10);
+            const labels = ['None', 'Light', 'Moderate', 'Severe', 'Critical', 'Emergency', 'Shutdown'];
+            thermalStatus = `${labels[code] ?? 'Unknown'} (${code})`;
+        }
+    }
+    // 4. Memory telemetry
+    const memRes = await runAdb(['-s', serial, 'shell', 'cat', '/proc/meminfo']);
+    let memTotal = 'N/A';
+    let memAvail = 'N/A';
+    let memPct = 'N/A';
+    if (memRes.ok) {
+        const totalMatch = memRes.stdout.match(/MemTotal:\s+(\d+)\s+kB/);
+        const availMatch = memRes.stdout.match(/MemAvailable:\s+(\d+)\s+kB/);
+        if (totalMatch && availMatch) {
+            const totalMB = Math.round(parseInt(totalMatch[1], 10) / 1024);
+            const availMB = Math.round(parseInt(availMatch[1], 10) / 1024);
+            memTotal = `${totalMB} MB`;
+            memAvail = `${availMB} MB`;
+            memPct = `${Math.round((availMB / totalMB) * 100)}% available`;
+        }
+    }
+    // 5. AICore status
+    const aicoreRes = await runAdb(['-s', serial, 'shell', 'pm', 'list', 'packages', 'com.google.android.aicore']);
+    const aicoreInstalled = aicoreRes.ok && aicoreRes.stdout.includes('com.google.android.aicore');
+    // Print Telemetry Matrix
+    console.log(`\n${ANSI.bold}Hardware Telemetry Snapshot:${ANSI.reset}`);
+    console.log(`  Device:       ${manufacturer} ${model} (Android ${release}, API ${sdk})`);
+    console.log(`  Silicon:      ${soc}`);
+    console.log(`  Battery:      ${batteryLevel} · ${batteryTemp} · ${batteryVoltage} · ${batteryStatus} (${batteryHealth})`);
+    console.log(`  Thermals:     ${thermalStatus}`);
+    console.log(`  Memory:       ${memAvail} / ${memTotal} (${memPct})`);
+    console.log(`  AICore:       ${aicoreInstalled ? `${ANSI.green}Active${ANSI.reset}` : `${ANSI.yellow}Not Installed${ANSI.reset}`}\n`);
+    const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+    const userQuery = flags.query || 'Perform a comprehensive hardware diagnostic check on this Pixel device.';
+    if (!apiKey) {
+        console.log(`${ANSI.bold}Autonomous Diagnostic Assessment (Local Heuristics):${ANSI.reset}`);
+        const issues = [];
+        if (batteryHealth !== 'Good' && batteryHealth !== 'N/A')
+            issues.push('Battery reports degraded health.');
+        if (thermalStatus.includes('Severe') || thermalStatus.includes('Critical'))
+            issues.push('Thermal throttling active.');
+        if (!aicoreInstalled)
+            issues.push('AICore is not installed; Gemini Nano hardware acceleration disabled.');
+        if (issues.length === 0) {
+            console.log(`  ${ANSI.green}✔ System hardware health nominal. All silicon, battery, and thermal parameters within optimal operational thresholds.${ANSI.reset}`);
+        }
+        else {
+            for (const iss of issues) {
+                console.log(`  ${ANSI.yellow}⚠ ${iss}${ANSI.reset}`);
+            }
+        }
+        console.log(`\n${ANSI.dim}💡 Tip: Export GEMINI_API_KEY to activate cloud agent multi-turn LLM reasoning and custom hardware triage queries.${ANSI.reset}`);
+        return 0;
+    }
+    // Cloud Agent Reasoning
+    const modelName = flags.model || 'gemini-2.5-flash';
+    console.log(`${ANSI.bold}Cloud Hardware Agent (${modelName}):${ANSI.reset}`);
+    console.log(`${ANSI.dim}Reasoning over hardware telemetry with Google Gen AI...${ANSI.reset}\n`);
+    const prompt = `Target Device Telemetry:
+- Manufacturer: ${manufacturer}
+- Model: ${model}
+- Android Release: ${release} (SDK ${sdk})
+- SoC Silicon: ${soc}
+- Battery: Level=${batteryLevel}, Temp=${batteryTemp}, Voltage=${batteryVoltage}, Status=${batteryStatus}, Health=${batteryHealth}
+- Thermal Headroom: ${thermalStatus}
+- Memory: Available=${memAvail}, Total=${memTotal} (${memPct})
+- AICore: ${aicoreInstalled ? 'Installed and available' : 'Not installed'}
+
+User Diagnostic Query: "${userQuery}"
+
+Provide a concise, professional hardware engineering assessment. Evaluate thermal headroom, battery wear/charging, memory constraints, and AICore readiness. Give specific actionable recommendations.`;
+    try {
+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelName)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                contents: [{ role: 'user', parts: [{ text: prompt }] }],
+                systemInstruction: {
+                    parts: [{ text: 'You are the PixelKit Hardware Diagnostics Agent, an expert embedded and systems engineer specializing in Google Pixel hardware (Tensor G-series, Android, AICore).' }]
+                }
+            })
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            console.error(`Agent API error (${res.status}): ${errText}`);
+            return 1;
+        }
+        const data = await res.json();
+        const replyText = data?.candidates?.[0]?.content?.parts?.[0]?.text;
+        if (replyText) {
+            console.log(replyText.trim());
+            console.log(`\n${ANSI.green}✔ Hardware diagnostic triage complete.${ANSI.reset}`);
+            return 0;
+        }
+        else {
+            console.error('No response text received from agent.');
+            return 1;
+        }
+    }
+    catch (err) {
+        console.error(`Agent reasoning failed: ${err.message || String(err)}`);
+        return 1;
+    }
+}
 /**
  * Runs all six checks in order and prints them. Returns the process exit code: 0 only when every
  * check passed or was not applicable; 1 when any check failed or — per the "never fabricate a
@@ -416,15 +605,19 @@ async function main() {
         process.exitCode = 1;
         return;
     }
-    if (command !== 'doctor') {
-        console.error(`Unknown command "${command}". The only command is "doctor".\n`);
-        printUsage();
-        process.exitCode = 1;
+    if (command === 'doctor') {
+        process.exitCode = await doctor(flags);
+        return;
+    }
+    if (command === 'agent') {
+        process.exitCode = await runHardwareAgent(flags);
         return;
     }
-    process.exitCode = await doctor(flags);
+    console.error(`Unknown command "${command}". Available commands: "doctor", "agent".\n`);
+    printUsage();
+    process.exitCode = 1;
 }
 main().catch((err) => {
-    console.error(`pixelkit doctor crashed: ${err.stack || String(err)}`);
+    console.error(`pixelkit crashed: ${err.stack || String(err)}`);
     process.exitCode = 1;
 });