@elizaos/app-core 2.0.0-beta.3 → 2.0.3-beta.3

package/platforms/android/app/src/main/java/ai/elizaos/app/GatewayConnectionService.java

@@ -14,6 +14,8 @@ import android.os.IBinder;
 
 import androidx.core.app.NotificationCompat;
 
+import ai.elizaos.app.R;
+
 /**
  * Foreground service that keeps the Android process alive so the Capacitor
  * gateway plugin can maintain its WebSocket connection while the app is in
@@ -29,11 +31,17 @@ public class GatewayConnectionService extends Service {
     private static final int NOTIFICATION_ID = 1;
 
     // Intent actions
-    private static final String ACTION_STOP = "ai.elizaos.app.action.STOP_GATEWAY";
-    private static final String ACTION_UPDATE_STATUS = "ai.elizaos.app.action.UPDATE_STATUS";
+    private static final String ACTION_STOP = "app.eliza.action.STOP_GATEWAY";
+    private static final String ACTION_UPDATE_STATUS = "app.eliza.action.UPDATE_STATUS";
 
     // Extras
     private static final String EXTRA_STATUS = "status";
+    private static final String EXTRA_STOP_SOURCE = "stopSource";
+    private static final String STOP_SOURCE_NOTIFICATION = "notification";
+
+    // Mirrors @capacitor/preferences default group and MOBILE_RUNTIME_MODE_STORAGE_KEY.
+    private static final String CAPACITOR_PREFS_GROUP = "CapacitorStorage";
+    private static final String RUNTIME_MODE_KEY = "eliza:mobile-runtime-mode";
 
     // Connection status constants — kept in sync with JS plugin events.
     public static final String STATUS_CONNECTED = "connected";
@@ -49,7 +57,7 @@ public class GatewayConnectionService extends Service {
         super.onCreate();
         ensureNotificationChannel();
 
-        Notification notification = buildNotification("elizaOS Gateway", "Starting…");
+        Notification notification = buildNotification("Eliza Gateway", "Starting…");
 
         // API 34+ requires explicit foreground service type when calling startForeground().
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
@@ -68,6 +76,10 @@ public class GatewayConnectionService extends Service {
         if (intent != null) {
             String action = intent.getAction();
             if (ACTION_STOP.equals(action)) {
+                if (isNotificationStop(intent) && isCloudRuntimeModeLocked()) {
+                    updateNotification();
+                    return START_STICKY;
+                }
                 stopSelf();
                 return START_NOT_STICKY;
             }
@@ -111,7 +123,7 @@ public class GatewayConnectionService extends Service {
             "Gateway Connection",
             NotificationManager.IMPORTANCE_LOW
         );
-        channel.setDescription("Shows elizaOS gateway connection status");
+        channel.setDescription("Shows Eliza gateway connection status");
         channel.setShowBadge(false);
 
         NotificationManager mgr = getSystemService(NotificationManager.class);
@@ -129,24 +141,46 @@ public class GatewayConnectionService extends Service {
             PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
         );
 
-        // "Disconnect" action in the notification.
-        Intent stopIntent = new Intent(this, GatewayConnectionService.class);
-        stopIntent.setAction(ACTION_STOP);
-        PendingIntent stopPending = PendingIntent.getService(
-            this, 2, stopIntent,
-            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
-        );
-
-        return new NotificationCompat.Builder(this, CHANNEL_ID)
+        NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
             .setSmallIcon(R.mipmap.ic_launcher)
             .setContentTitle(title)
             .setContentText(text)
             .setContentIntent(launchPending)
             .setOngoing(true)
             .setOnlyAlertOnce(true)
-            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
-            .addAction(0, "Disconnect", stopPending)
-            .build();
+            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE);
+
+        if (!isCloudRuntimeModeLocked()) {
+            // "Disconnect" is only safe in local/non-cloud modes.
+            Intent stopIntent = new Intent(this, GatewayConnectionService.class);
+            stopIntent.setAction(ACTION_STOP);
+            stopIntent.putExtra(EXTRA_STOP_SOURCE, STOP_SOURCE_NOTIFICATION);
+            PendingIntent stopPending = PendingIntent.getService(
+                this, 2, stopIntent,
+                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
+            );
+            builder.addAction(0, "Disconnect", stopPending);
+        }
+
+        return builder.build();
+    }
+
+    private boolean isNotificationStop(Intent intent) {
+        return STOP_SOURCE_NOTIFICATION.equals(intent.getStringExtra(EXTRA_STOP_SOURCE));
+    }
+
+    private boolean isCloudRuntimeModeLocked() {
+        String mode = readRuntimeMode();
+        return "cloud".equals(mode) || "cloud-hybrid".equals(mode);
+    }
+
+    private String readRuntimeMode() {
+        try {
+            return getSharedPreferences(CAPACITOR_PREFS_GROUP, Context.MODE_PRIVATE)
+                .getString(RUNTIME_MODE_KEY, null);
+        } catch (Exception e) {
+            return null;
+        }
     }
 
     /** Push an updated notification to reflect the current connection status. */
@@ -156,15 +190,15 @@ public class GatewayConnectionService extends Service {
 
         switch (currentStatus) {
             case STATUS_CONNECTED:
-                title = "elizaOS Gateway · Connected";
+                title = "Eliza Gateway · Connected";
                 text = "WebSocket connection active";
                 break;
             case STATUS_RECONNECTING:
-                title = "elizaOS Gateway · Reconnecting";
+                title = "Eliza Gateway · Reconnecting";
                 text = "Attempting to restore connection…";
                 break;
             default:
-                title = "elizaOS Gateway";
+                title = "Eliza Gateway";
                 text = "Disconnected";
                 break;
         }

package/platforms/android/app/src/main/java/ai/elizaos/app/MainActivity.java

@@ -5,19 +5,28 @@ import android.content.pm.PackageManager;
 import android.os.Build;
 import android.os.Bundle;
 import android.util.Log;
+import android.view.WindowManager;
 import android.webkit.WebSettings;
 import android.webkit.WebView;
 
 import androidx.core.content.ContextCompat;
+import androidx.core.splashscreen.SplashScreen;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowCompat;
+import androidx.core.view.WindowInsetsCompat;
+import androidx.core.view.WindowInsetsControllerCompat;
 
 import com.getcapacitor.BridgeActivity;
 
+import ai.elizaos.app.BuildConfig;
+
 import java.lang.reflect.Method;
 
 public class MainActivity extends BridgeActivity {
 
     private static final String TAG = "ElizaMainActivity";
-    private static final int REQUEST_NOTIFICATION_PERMISSION = 1001;
+
+    private static final int REQUEST_CODE_POST_NOTIFICATIONS = 1001;
 
     /**
      * One UA marker entry. The MainActivity reads `systemProp` via
@@ -52,11 +61,18 @@ public class MainActivity extends BridgeActivity {
      */
     private static final UserAgentMarker[] BRAND_USER_AGENT_MARKERS = new UserAgentMarker[] {
         new UserAgentMarker("ro.elizaos.product", "ElizaOS/"),
-        // BRAND_USER_AGENT_MARKERS_INJECTION_POINT
     };
 
     @Override
     protected void onCreate(Bundle savedInstanceState) {
+        // Install the AndroidX splash screen BEFORE super.onCreate so it swaps
+        // the launch theme (AppTheme.NoActionBarLaunch / Theme.SplashScreen) to
+        // the activity's postSplashScreenTheme (AppTheme.NoActionBar). Without
+        // it the splash theme persists and Android renders a native AppCompat
+        // action bar — the orange "Eliza" top bar with splash.png stretched
+        // across it — above the Capacitor WebView.
+        SplashScreen.installSplashScreen(this);
+
         // Per Android docs, must precede the first WebView instantiation.
         // BridgeActivity.super.onCreate constructs the Capacitor WebView,
         // so the toggle is set first to stay race-proof against future
@@ -66,31 +82,44 @@ public class MainActivity extends BridgeActivity {
         }
 
         registerPlugin(AgentPlugin.class);
+        registerPlugin(BatteryOptimizationPlugin.class);
+        registerPlugin(VoiceCapturePlugin.class);
+        registerPlugin(ElizaVoicePlugin.class);
+        registerPlugin(ResourceProbePlugin.class);
         super.onCreate(savedInstanceState);
 
-        // The Capacitor WebView serves the renderer at https://localhost
-        // (its default secure-context origin); the on-device Eliza agent
-        // listens at http://127.0.0.1:31337. Without this knob the WebView
-        // blocks every fetch to the loopback agent as a mixed-content
-        // upgrade, surfacing in the UI as "Backend Timeout: /api/auth/status
-        // - Failed to fetch" even though the agent is up. Granting
-        // MIXED_CONTENT_ALWAYS_ALLOW only matters for loopback in this app
-        // — the network_security_config still pins the WebView's allowed
-        // cleartext hosts, and the Capacitor server.hostname locks the
-        // page origin.
+        // Keep the screen on while the agent app is in the foreground.
+        // Voice turns (ASR → LLM → TTS) on local-runtime builds regularly
+        // take 1-5 seconds; screen-off mid-turn breaks the "is the agent
+        // still working?" feedback and confuses the user. The flag is
+        // window-scoped — Android releases it automatically when the window
+        // is no longer visible (app moved to background or fully covered),
+        // so background instances don't drain battery. Same flag set by
+        // every video / voice-calling app (Snapchat, YouTube, Zoom, Meet).
+        getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+
+        // Hide the bottom system navigation bar (the white gesture pill) for a
+        // clean, full-bleed agent home — iOS-style. We hide ONLY the navigation
+        // bars, never the status bar (the system clock/battery stay). Transient-
+        // by-swipe so the user can still reveal it with an edge swipe; re-applied
+        // in onWindowFocusChanged so it stays hidden after dialogs / resume.
+        applyImmersiveNavigationBar();
+
         if (getBridge() != null && getBridge().getWebView() != null) {
             WebSettings settings = getBridge().getWebView().getSettings();
-            settings.setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW);
+            settings.setMixedContentMode(resolveMixedContentMode());
             applyBrandUserAgentMarkers(settings);
             // Synchronous fast path for the on-device agent bearer that
             // bypasses Capacitor's plugin executor. See ElizaNativeBridge
             // for the dead-Handler bug it works around.
             getBridge().getWebView().addJavascriptInterface(
-                new ElizaNativeBridge(), ElizaNativeBridge.JS_NAME);
+                new ElizaNativeBridge(this), ElizaNativeBridge.JS_NAME);
+            ElizaAndroidSystemBridge.install(getBridge().getWebView(), this);
+            publishGestureInset();
         }
 
         // Auto-start the local Eliza agent runtime as a foreground service.
-        // shouldAutoStart() returns true on branded devices (AOSP/MiladyOS —
+        // shouldAutoStart() returns true on branded devices (AOSP/ElizaOS —
         // the device IS the agent) and on stock Android only when the user
         // picked Local mode in onboarding. Cloud/Remote modes skip this so
         // we don't burn battery on a service they never call. The boot
@@ -98,7 +127,121 @@ public class MainActivity extends BridgeActivity {
         // the user opens the app.
         if (ElizaAgentService.shouldAutoStart(this)) {
             ElizaAgentService.start(this);
+            // Ask for notification consent only once the user (or the device
+            // image) has actually committed to running the on-device agent.
+            // A fresh stock install auto-starts the service so the dashboard
+            // has something to talk to, but the user has chosen nothing yet —
+            // cold-asking there is the first-run nag we want to avoid
+            // (iOS-style: ask only when there is a reason). The foreground
+            // service still runs without the grant; its notification is just
+            // suppressed until later granted in settings or on a later launch
+            // once a runtime mode is persisted.
+            if (ElizaAgentService.hasCommittedRuntimeChoice(this)) {
+                requestPostNotificationsIfNeeded();
+            }
         }
+
+        ElizaWorkScheduler.enqueuePeriodic(getApplicationContext());
+    }
+
+    @Override
+    public void onWindowFocusChanged(boolean hasFocus) {
+        super.onWindowFocusChanged(hasFocus);
+        // The system restores the nav bar after dialogs / resume; re-hide it
+        // whenever we regain focus so the full-bleed home stays clean.
+        if (hasFocus) {
+            applyImmersiveNavigationBar();
+        }
+    }
+
+    /**
+     * Hide the bottom navigation bar (gesture pill) while keeping the status
+     * bar. Uses the AndroidX controller so it is correct across API levels;
+     * transient-by-swipe so the bar is still reachable.
+     */
+    private void applyImmersiveNavigationBar() {
+        try {
+            WindowCompat.setDecorFitsSystemWindows(getWindow(), false);
+            WindowInsetsControllerCompat controller =
+                WindowCompat.getInsetsController(
+                    getWindow(), getWindow().getDecorView());
+            if (controller != null) {
+                controller.hide(WindowInsetsCompat.Type.navigationBars());
+                controller.setSystemBarsBehavior(
+                    WindowInsetsControllerCompat
+                        .BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
+                // The status bar stays visible over the live orange ambient
+                // home, so its icons must be light (white). Paired with the
+                // transparent android:statusBarColor in styles.xml, the orange
+                // draws full-bleed under the clock/battery — no flat band.
+                controller.setAppearanceLightStatusBars(false);
+            }
+        } catch (Exception e) {
+            Log.w(TAG, "Failed to apply immersive navigation bar", e);
+        }
+    }
+
+    /**
+     * Publish the bottom gesture-navigation inset (the home-pill zone apps must
+     * not put critical UI under) to the WebView as the CSS var
+     * `--android-gesture-inset-bottom`. We hide the navigation bar, which zeroes
+     * `env(safe-area-inset-bottom)`, so the floating chat composer would
+     * otherwise sit on top of the gesture-home zone. The renderer folds this var
+     * into its bottom clearance via max(); it defaults to 0px off-Android.
+     */
+    private void publishGestureInset() {
+        final WebView webView = getBridge() != null ? getBridge().getWebView() : null;
+        if (webView == null) {
+            return;
+        }
+        ViewCompat.setOnApplyWindowInsetsListener(
+            getWindow().getDecorView(),
+            (v, insets) -> {
+                int px = insets
+                    .getInsets(WindowInsetsCompat.Type.mandatorySystemGestures())
+                    .bottom;
+                float dp = px / getResources().getDisplayMetrics().density;
+                String js =
+                    "document.documentElement.style.setProperty("
+                        + "'--android-gesture-inset-bottom','" + dp + "px')";
+                webView.post(() -> webView.evaluateJavascript(js, null));
+                return insets;
+            });
+        ViewCompat.requestApplyInsets(getWindow().getDecorView());
+    }
+
+    private static int resolveMixedContentMode() {
+        // The local/AOSP app serves the renderer from Capacitor's
+        // https://localhost origin while the on-device agent listens on
+        // http://127.0.0.1:31337. Debug sideload builds and privileged AOSP
+        // builds need that loopback bridge; cloud/Play rewrites this
+        // activity and keeps mixed content blocked.
+        if (BuildConfig.DEBUG || BuildConfig.AOSP_BUILD) {
+            return WebSettings.MIXED_CONTENT_ALWAYS_ALLOW;
+        }
+        return WebSettings.MIXED_CONTENT_NEVER_ALLOW;
+    }
+
+    /**
+     * On API 33+ (Tiramisu) Android requires runtime consent for posting
+     * notifications. The foreground gateway service already declares the
+     * permission in the manifest, but without runtime grant its notification
+     * is suppressed. We request it lazily and non-blockingly here — if the
+     * user denies, the FGS still runs and pushes notifications only when
+     * later re-granted in system settings.
+     */
+    private void requestPostNotificationsIfNeeded() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            return;
+        }
+        int state = ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS);
+        if (state == PackageManager.PERMISSION_GRANTED) {
+            return;
+        }
+        requestPermissions(
+            new String[] { Manifest.permission.POST_NOTIFICATIONS },
+            REQUEST_CODE_POST_NOTIFICATIONS
+        );
     }
 
     @Override
@@ -134,8 +277,8 @@ public class MainActivity extends BridgeActivity {
      * Iterate over `BRAND_USER_AGENT_MARKERS` and append each marker's
      * `<uaPrefix><tag>` token to the WebView's User-Agent when the
      * named system property is non-empty. On stock Android no marker
-     * matches and the UA is left untouched, preserving the
-     * RuntimeGate picker. Idempotent — already-present markers aren't
+     * matches and the UA is left untouched, preserving first-run runtime
+     * setup. Idempotent — already-present markers aren't
      * duplicated.
      *
      * The framework's default `ro.elizaos.product` → `ElizaOS/` entry
@@ -183,20 +326,4 @@ public class MainActivity extends BridgeActivity {
         }
     }
 
-    /**
-     * On Android 13+ (API 33), POST_NOTIFICATIONS is a runtime permission.
-     * Without it, the foreground service notification is silently suppressed.
-     */
-    private void requestNotificationPermissionIfNeeded() {
-        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
-            return;
-        }
-        int result = ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS);
-        if (result != PackageManager.PERMISSION_GRANTED) {
-            requestPermissions(
-                new String[]{ Manifest.permission.POST_NOTIFICATIONS },
-                REQUEST_NOTIFICATION_PERMISSION
-            );
-        }
-    }
 }

package/platforms/android/app/src/main/java/ai/elizaos/app/ResourceProbePlugin.java

@@ -0,0 +1,169 @@
+package ai.elizaos.app;
+
+import android.app.ActivityManager;
+import android.content.Context;
+import android.os.BatteryManager;
+import android.os.Build;
+import android.os.Debug;
+import android.os.PowerManager;
+import android.system.Os;
+import android.system.OsConstants;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import org.json.JSONObject;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+/**
+ * Capacitor plugin that surfaces a live device-resource snapshot to JS for the
+ * Mobile Resource Workbench (issue #8800) — the Android parity of the iOS
+ * {@code ElizaIntent.getResourceSnapshot}.
+ *
+ * <p>Reads:
+ * <ul>
+ *   <li><b>thermalState</b> — {@link PowerManager#getCurrentThermalStatus()}
+ *       (API 29+), mapped to the shared {@code nominal/fair/serious/critical}
+ *       model; {@code "unknown"} on older OSes.</li>
+ *   <li><b>battery</b> — {@link BatteryManager} level (%), charge counter (µAh),
+ *       instantaneous current (µA), and charging flag.</li>
+ *   <li><b>memory</b> — {@link Debug#getMemoryInfo} total PSS (the app's real
+ *       footprint) plus {@link ActivityManager.MemoryInfo} device available RAM.</li>
+ *   <li><b>cpuTimeMs</b> — process user+system jiffies from {@code /proc/self/stat}
+ *       converted via {@code sysconf(_SC_CLK_TCK)}.</li>
+ *   <li><b>lowPowerMode</b> — {@link PowerManager#isPowerSaveMode()}.</li>
+ * </ul>
+ *
+ * <p>Every value the OS cannot provide is returned as JSON {@code null}, never a
+ * fabricated zero (AGENTS.md §3/§7).
+ */
+@CapacitorPlugin(name = "ResourceProbe")
+public class ResourceProbePlugin extends Plugin {
+
+    @PluginMethod
+    public void getResourceSnapshot(PluginCall call) {
+        Context context = getContext();
+        JSObject result = new JSObject();
+        result.put("platform", "android");
+
+        result.put("thermalState", readThermalState(context));
+        result.put("lowPowerMode", readPowerSaveMode(context));
+
+        BatteryManager bm = (BatteryManager) context.getSystemService(Context.BATTERY_SERVICE);
+        result.put("batteryLevelPct", readBatteryProperty(bm, BatteryManager.BATTERY_PROPERTY_CAPACITY));
+        result.put("batteryChargeMicroAmpHours",
+            readBatteryProperty(bm, BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER));
+        result.put("batteryCurrentMicroAmps",
+            readBatteryProperty(bm, BatteryManager.BATTERY_PROPERTY_CURRENT_NOW));
+        result.put("isCharging", bm != null && bm.isCharging());
+
+        result.put("residentMemoryMb", readTotalPssMb());
+        result.put("availableRamMb", readAvailableRamMb(context));
+        result.put("cpuTimeMs", readProcessCpuTimeMs());
+
+        result.put("capturedAtMs", System.currentTimeMillis());
+        call.resolve(result);
+    }
+
+    private static String readThermalState(Context context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+            return "unknown";
+        }
+        PowerManager pm = (PowerManager) context.getSystemService(Context.POWER_SERVICE);
+        if (pm == null) {
+            return "unknown";
+        }
+        switch (pm.getCurrentThermalStatus()) {
+            case PowerManager.THERMAL_STATUS_NONE:
+                return "nominal";
+            case PowerManager.THERMAL_STATUS_LIGHT:
+            case PowerManager.THERMAL_STATUS_MODERATE:
+                return "fair";
+            case PowerManager.THERMAL_STATUS_SEVERE:
+            case PowerManager.THERMAL_STATUS_CRITICAL:
+                return "serious";
+            case PowerManager.THERMAL_STATUS_EMERGENCY:
+            case PowerManager.THERMAL_STATUS_SHUTDOWN:
+                return "critical";
+            default:
+                return "unknown";
+        }
+    }
+
+    private static Object readPowerSaveMode(Context context) {
+        PowerManager pm = (PowerManager) context.getSystemService(Context.POWER_SERVICE);
+        return pm != null ? (Object) pm.isPowerSaveMode() : JSONObject.NULL;
+    }
+
+    /** A BatteryManager integer property, or JSON null when unavailable/sentinel. */
+    private static Object readBatteryProperty(BatteryManager bm, int property) {
+        if (bm == null) {
+            return JSONObject.NULL;
+        }
+        int value = bm.getIntProperty(property);
+        // BatteryManager returns Integer.MIN_VALUE for unsupported properties.
+        return value == Integer.MIN_VALUE ? JSONObject.NULL : (Object) value;
+    }
+
+    /** Total PSS of this process in MB, or JSON null when the probe fails. */
+    private static Object readTotalPssMb() {
+        try {
+            Debug.MemoryInfo info = new Debug.MemoryInfo();
+            Debug.getMemoryInfo(info);
+            // getTotalPss() is in KB.
+            return info.getTotalPss() / 1024.0;
+        } catch (RuntimeException e) {
+            return JSONObject.NULL;
+        }
+    }
+
+    private static Object readAvailableRamMb(Context context) {
+        ActivityManager am = (ActivityManager) context.getSystemService(Context.ACTIVITY_SERVICE);
+        if (am == null) {
+            return JSONObject.NULL;
+        }
+        ActivityManager.MemoryInfo info = new ActivityManager.MemoryInfo();
+        am.getMemoryInfo(info);
+        return info.availMem / 1_048_576.0;
+    }
+
+    /**
+     * Process user+system CPU time in ms from {@code /proc/self/stat} fields 14
+     * (utime) and 15 (stime), in clock ticks, converted via
+     * {@code sysconf(_SC_CLK_TCK)}.
+     */
+    private static Object readProcessCpuTimeMs() {
+        try {
+            byte[] raw = Files.readAllBytes(Paths.get("/proc/self/stat"));
+            String stat = new String(raw, StandardCharsets.UTF_8);
+            // The comm field (2nd) is parenthesised and may contain spaces; split
+            // after the closing ')' so the remaining fields are space-delimited.
+            int close = stat.lastIndexOf(')');
+            if (close < 0 || close + 2 > stat.length()) {
+                return JSONObject.NULL;
+            }
+            String[] fields = stat.substring(close + 2).trim().split("\\s+");
+            // After comm, field index 0 is "state"; utime is field 14 and stime
+            // field 15 in the 1-based proc layout → indices 11 and 12 here.
+            if (fields.length < 13) {
+                return JSONObject.NULL;
+            }
+            long utime = Long.parseLong(fields[11]);
+            long stime = Long.parseLong(fields[12]);
+            long ticksPerSecond = Os.sysconf(OsConstants._SC_CLK_TCK);
+            if (ticksPerSecond <= 0) {
+                ticksPerSecond = 100; // POSIX-conventional default on Android
+            }
+            return ((utime + stime) * 1000.0) / ticksPerSecond;
+        } catch (IOException | RuntimeException e) {
+            return JSONObject.NULL;
+        }
+    }
+}