@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/device-resource-metrics.d.ts

@@ -0,0 +1,149 @@
+/**
+ * DeviceResourceMetrics — on-device resource profiling accumulator.
+ *
+ * Sibling to `VoiceRunMetrics` (`latency-trace.ts`), generalised for the Mobile
+ * Resource Workbench (issue #8800). Where `VoiceRunMetrics` accumulates the
+ * non-latency signals of a *host-side* voice run (server RSS, MTP accept-rate),
+ * this accumulates the signals of an *on-device* agent run:
+ *
+ *   - per-generation **prefill / decode / combined tokens-per-second** + TTFT
+ *     (fed from the device-bridge `computeGenerationThroughput` differencing),
+ *   - **peak + steady resident memory (RSS)** with an RSS-leak flag,
+ *   - **battery drain** (% and, where the OS exposes a charge counter, µAh),
+ *   - a **thermal-state timeline** + transition count,
+ *   - **low-power-mode transitions**.
+ *
+ * Every field is optional on input and every output is `null` when nothing
+ * could be measured — a quantity the device could not report is recorded as
+ * missing, never as a fabricated `0` (AGENTS.md §3 / §7). The workbench writes
+ * `summary()` to `results/<workload>/latest.json`.
+ */
+import { type HistogramSummary } from "./latency-trace";
+export type DeviceThermalState = "nominal" | "fair" | "serious" | "critical" | "unknown";
+/** A single generation's differenced throughput (see `throughput.ts`). */
+export interface GenerationObservation {
+    prefillTokensPerSecond?: number | null;
+    decodeTokensPerSecond?: number | null;
+    combinedTokensPerSecond?: number | null;
+    ttftMs?: number | null;
+}
+/**
+ * A sampled device-resource snapshot, taken on an interval across a workload.
+ * Sourced from the native `getResourceSnapshot` bridge (iOS/Android) and/or
+ * host-side OS probes (`adb dumpsys`, `/proc`).
+ */
+export interface ResourceSample {
+    /** Timestamp in ms (epoch or run-relative); orders the timeline + drain rate. */
+    atMs: number;
+    /** Resident set size in MB (peak / steady / leak tracking). */
+    residentMemoryMb?: number | null;
+    /** Available device RAM in MB at sample time. */
+    availableRamMb?: number | null;
+    /** Battery level 0..100. */
+    batteryLevelPct?: number | null;
+    /** Cumulative charge counter in µAh (Android `BATTERY_PROPERTY_CHARGE_COUNTER`). */
+    batteryChargeMicroAmpHours?: number | null;
+    /** Whether the device was charging at sample time. */
+    isCharging?: boolean | null;
+    thermalState?: DeviceThermalState | null;
+    lowPowerMode?: boolean | null;
+    /** Cumulative process CPU time in ms, when the platform exposes it. */
+    cpuTimeMs?: number | null;
+}
+export interface RssSummary {
+    firstMb: number | null;
+    lastMb: number | null;
+    peakMb: number | null;
+    /** Median RSS over the back half of the run (warm/steady state). */
+    steadyMb: number | null;
+    samples: number;
+    /** lastMb − firstMb, or null. */
+    growthMb: number | null;
+    /** True when RSS is monotone non-decreasing across ≥4 samples and grew past the threshold. */
+    leakSuspected: boolean;
+}
+export interface BatterySummary {
+    firstPct: number | null;
+    lastPct: number | null;
+    /** firstPct − lastPct (positive = battery consumed), or null. */
+    drainPct: number | null;
+    samples: number;
+    /** True if any sample reported charging (drain numbers are then unreliable). */
+    chargingObserved: boolean;
+    /** firstCharge − lastCharge in µAh (positive = consumed), when the counter is present. */
+    energyMicroAmpHoursDelta: number | null;
+    /** Wall-clock span across battery samples in ms, or null. */
+    durationMs: number | null;
+}
+export interface ThermalTransition {
+    atMs: number;
+    state: DeviceThermalState;
+}
+export interface ThermalSummary {
+    samples: number;
+    initialState: DeviceThermalState | null;
+    /** Worst (highest-severity) known state observed. */
+    maxState: DeviceThermalState | null;
+    /** State-change timeline (first known state + every change after). */
+    transitions: ThermalTransition[];
+    transitionCount: number;
+    /** Fraction of known-state samples at serious|critical, or null when no known state. */
+    fractionThrottled: number | null;
+}
+export interface LowPowerSummary {
+    samples: number;
+    everEnabled: boolean;
+    transitionCount: number;
+}
+export interface DeviceResourceSummary {
+    generations: number;
+    resourceSamples: number;
+    prefillTokensPerSecond: HistogramSummary;
+    decodeTokensPerSecond: HistogramSummary;
+    combinedTokensPerSecond: HistogramSummary;
+    ttftMs: HistogramSummary;
+    rss: RssSummary;
+    battery: BatterySummary;
+    thermal: ThermalSummary;
+    lowPowerMode: LowPowerSummary;
+}
+export declare class DeviceResourceMetrics {
+    private readonly opts;
+    private generations;
+    private readonly prefillHist;
+    private readonly decodeHist;
+    private readonly combinedHist;
+    private readonly ttftHist;
+    private readonly rssSamples;
+    private resourceSamples;
+    private firstBattery;
+    private lastBattery;
+    private firstChargeUah;
+    private lastChargeUah;
+    private batterySampleCount;
+    private chargingObserved;
+    private thermalSampleCount;
+    private thermalInitial;
+    private thermalLast;
+    private thermalMaxRank;
+    private thermalMaxState;
+    private thermalThrottledCount;
+    private thermalKnownCount;
+    private readonly thermalTransitions;
+    private lowPowerSampleCount;
+    private lowPowerEver;
+    private lowPowerLast;
+    private lowPowerTransitions;
+    constructor(opts?: {
+        leakGrowthMbThreshold?: number;
+    });
+    /** Record one generation's differenced throughput. */
+    recordGeneration(obs: GenerationObservation): void;
+    /** Record one sampled device-resource snapshot. */
+    recordResourceSample(sample: ResourceSample): void;
+    private rssSummary;
+    private batterySummary;
+    private thermalSummary;
+    summary(): DeviceResourceSummary;
+}
+//# sourceMappingURL=device-resource-metrics.d.ts.map

package/src/services/device-resource-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-resource-metrics.d.ts","sourceRoot":"","sources":["device-resource-metrics.ts"],"names":[],"mappings":"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"}

package/src/services/device-resource-metrics.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { DeviceResourceMetrics } from "./device-resource-metrics";
+
+describe("DeviceResourceMetrics", () => {
+	it("summarizes generation throughput and sampled device resources", () => {
+		const metrics = new DeviceResourceMetrics({ leakGrowthMbThreshold: 100 });
+
+		metrics.recordGeneration({
+			prefillTokensPerSecond: 320,
+			decodeTokensPerSecond: 160,
+			combinedTokensPerSecond: 128,
+			ttftMs: 200,
+		});
+		metrics.recordResourceSample({
+			atMs: 0,
+			residentMemoryMb: 1000,
+			batteryLevelPct: 80,
+			batteryChargeMicroAmpHours: 10_000,
+			isCharging: false,
+			thermalState: "nominal",
+			lowPowerMode: false,
+		});
+		metrics.recordResourceSample({
+			atMs: 1000,
+			residentMemoryMb: 1050,
+			batteryLevelPct: 79,
+			batteryChargeMicroAmpHours: 9900,
+			thermalState: "serious",
+			lowPowerMode: true,
+		});
+		metrics.recordResourceSample({
+			atMs: 2000,
+			residentMemoryMb: 1125,
+			batteryLevelPct: 78,
+			batteryChargeMicroAmpHours: 9800,
+			thermalState: "critical",
+			lowPowerMode: false,
+		});
+		metrics.recordResourceSample({
+			atMs: 3000,
+			residentMemoryMb: 1205,
+			batteryLevelPct: 77,
+			batteryChargeMicroAmpHours: 9700,
+			thermalState: "critical",
+			lowPowerMode: false,
+		});
+
+		const summary = metrics.summary();
+
+		expect(summary.generations).toBe(1);
+		expect(summary.prefillTokensPerSecond.p50).toBe(320);
+		expect(summary.decodeTokensPerSecond.p50).toBe(160);
+		expect(summary.combinedTokensPerSecond.p50).toBe(128);
+		expect(summary.ttftMs.p50).toBe(200);
+		expect(summary.rss).toMatchObject({
+			firstMb: 1000,
+			lastMb: 1205,
+			peakMb: 1205,
+			steadyMb: 1165,
+			growthMb: 205,
+			leakSuspected: true,
+		});
+		expect(summary.battery).toMatchObject({
+			firstPct: 80,
+			lastPct: 77,
+			drainPct: 3,
+			energyMicroAmpHoursDelta: 300,
+			durationMs: 3000,
+			chargingObserved: false,
+		});
+		expect(summary.thermal).toMatchObject({
+			initialState: "nominal",
+			maxState: "critical",
+			transitionCount: 2,
+			fractionThrottled: 0.75,
+		});
+		expect(summary.lowPowerMode).toMatchObject({
+			everEnabled: true,
+			transitionCount: 2,
+		});
+	});
+
+	it("keeps unmeasured quantities null instead of fabricating zeros", () => {
+		const metrics = new DeviceResourceMetrics();
+
+		metrics.recordGeneration({});
+		metrics.recordResourceSample({ atMs: 0 });
+
+		const summary = metrics.summary();
+
+		expect(summary.generations).toBe(1);
+		expect(summary.prefillTokensPerSecond.count).toBe(0);
+		expect(summary.prefillTokensPerSecond.p50).toBeNull();
+		expect(summary.rss.firstMb).toBeNull();
+		expect(summary.battery.drainPct).toBeNull();
+		expect(summary.thermal.fractionThrottled).toBeNull();
+	});
+});

package/src/services/device-resource-metrics.ts

@@ -0,0 +1,346 @@
+/**
+ * DeviceResourceMetrics — on-device resource profiling accumulator.
+ *
+ * Sibling to `VoiceRunMetrics` (`latency-trace.ts`), generalised for the Mobile
+ * Resource Workbench (issue #8800). Where `VoiceRunMetrics` accumulates the
+ * non-latency signals of a *host-side* voice run (server RSS, MTP accept-rate),
+ * this accumulates the signals of an *on-device* agent run:
+ *
+ *   - per-generation **prefill / decode / combined tokens-per-second** + TTFT
+ *     (fed from the device-bridge `computeGenerationThroughput` differencing),
+ *   - **peak + steady resident memory (RSS)** with an RSS-leak flag,
+ *   - **battery drain** (% and, where the OS exposes a charge counter, µAh),
+ *   - a **thermal-state timeline** + transition count,
+ *   - **low-power-mode transitions**.
+ *
+ * Every field is optional on input and every output is `null` when nothing
+ * could be measured — a quantity the device could not report is recorded as
+ * missing, never as a fabricated `0` (AGENTS.md §3 / §7). The workbench writes
+ * `summary()` to `results/<workload>/latest.json`.
+ */
+
+import { BoundedHistogram, type HistogramSummary } from "./latency-trace";
+
+export type DeviceThermalState =
+	| "nominal"
+	| "fair"
+	| "serious"
+	| "critical"
+	| "unknown";
+
+/** Severity rank for thermal states. `unknown` is unranked (excluded). */
+const THERMAL_RANK: Record<Exclude<DeviceThermalState, "unknown">, number> = {
+	nominal: 0,
+	fair: 1,
+	serious: 2,
+	critical: 3,
+};
+
+/** A single generation's differenced throughput (see `throughput.ts`). */
+export interface GenerationObservation {
+	prefillTokensPerSecond?: number | null;
+	decodeTokensPerSecond?: number | null;
+	combinedTokensPerSecond?: number | null;
+	ttftMs?: number | null;
+}
+
+/**
+ * A sampled device-resource snapshot, taken on an interval across a workload.
+ * Sourced from the native `getResourceSnapshot` bridge (iOS/Android) and/or
+ * host-side OS probes (`adb dumpsys`, `/proc`).
+ */
+export interface ResourceSample {
+	/** Timestamp in ms (epoch or run-relative); orders the timeline + drain rate. */
+	atMs: number;
+	/** Resident set size in MB (peak / steady / leak tracking). */
+	residentMemoryMb?: number | null;
+	/** Available device RAM in MB at sample time. */
+	availableRamMb?: number | null;
+	/** Battery level 0..100. */
+	batteryLevelPct?: number | null;
+	/** Cumulative charge counter in µAh (Android `BATTERY_PROPERTY_CHARGE_COUNTER`). */
+	batteryChargeMicroAmpHours?: number | null;
+	/** Whether the device was charging at sample time. */
+	isCharging?: boolean | null;
+	thermalState?: DeviceThermalState | null;
+	lowPowerMode?: boolean | null;
+	/** Cumulative process CPU time in ms, when the platform exposes it. */
+	cpuTimeMs?: number | null;
+}
+
+export interface RssSummary {
+	firstMb: number | null;
+	lastMb: number | null;
+	peakMb: number | null;
+	/** Median RSS over the back half of the run (warm/steady state). */
+	steadyMb: number | null;
+	samples: number;
+	/** lastMb − firstMb, or null. */
+	growthMb: number | null;
+	/** True when RSS is monotone non-decreasing across ≥4 samples and grew past the threshold. */
+	leakSuspected: boolean;
+}
+
+export interface BatterySummary {
+	firstPct: number | null;
+	lastPct: number | null;
+	/** firstPct − lastPct (positive = battery consumed), or null. */
+	drainPct: number | null;
+	samples: number;
+	/** True if any sample reported charging (drain numbers are then unreliable). */
+	chargingObserved: boolean;
+	/** firstCharge − lastCharge in µAh (positive = consumed), when the counter is present. */
+	energyMicroAmpHoursDelta: number | null;
+	/** Wall-clock span across battery samples in ms, or null. */
+	durationMs: number | null;
+}
+
+export interface ThermalTransition {
+	atMs: number;
+	state: DeviceThermalState;
+}
+
+export interface ThermalSummary {
+	samples: number;
+	initialState: DeviceThermalState | null;
+	/** Worst (highest-severity) known state observed. */
+	maxState: DeviceThermalState | null;
+	/** State-change timeline (first known state + every change after). */
+	transitions: ThermalTransition[];
+	transitionCount: number;
+	/** Fraction of known-state samples at serious|critical, or null when no known state. */
+	fractionThrottled: number | null;
+}
+
+export interface LowPowerSummary {
+	samples: number;
+	everEnabled: boolean;
+	transitionCount: number;
+}
+
+export interface DeviceResourceSummary {
+	generations: number;
+	resourceSamples: number;
+	prefillTokensPerSecond: HistogramSummary;
+	decodeTokensPerSecond: HistogramSummary;
+	combinedTokensPerSecond: HistogramSummary;
+	ttftMs: HistogramSummary;
+	rss: RssSummary;
+	battery: BatterySummary;
+	thermal: ThermalSummary;
+	lowPowerMode: LowPowerSummary;
+}
+
+const HISTOGRAM_CAPACITY = 1024;
+const DEFAULT_LEAK_GROWTH_MB = 256;
+/** Cap the thermal timeline so a long run cannot grow it without bound. */
+const MAX_THERMAL_TRANSITIONS = 256;
+
+function isFiniteNumber(v: number | null | undefined): v is number {
+	return typeof v === "number" && Number.isFinite(v);
+}
+
+function median(values: number[]): number | null {
+	if (values.length === 0) return null;
+	const s = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(s.length / 2);
+	return s.length % 2
+		? (s[mid] as number)
+		: ((s[mid - 1] as number) + (s[mid] as number)) / 2;
+}
+
+export class DeviceResourceMetrics {
+	private generations = 0;
+	private readonly prefillHist = new BoundedHistogram(HISTOGRAM_CAPACITY);
+	private readonly decodeHist = new BoundedHistogram(HISTOGRAM_CAPACITY);
+	private readonly combinedHist = new BoundedHistogram(HISTOGRAM_CAPACITY);
+	private readonly ttftHist = new BoundedHistogram(HISTOGRAM_CAPACITY);
+
+	private readonly rssSamples: number[] = [];
+
+	private resourceSamples = 0;
+	private firstBattery: { pct: number; atMs: number } | null = null;
+	private lastBattery: { pct: number; atMs: number } | null = null;
+	private firstChargeUah: number | null = null;
+	private lastChargeUah: number | null = null;
+	private batterySampleCount = 0;
+	private chargingObserved = false;
+
+	private thermalSampleCount = 0;
+	private thermalInitial: DeviceThermalState | null = null;
+	private thermalLast: DeviceThermalState | null = null;
+	private thermalMaxRank = -1;
+	private thermalMaxState: DeviceThermalState | null = null;
+	private thermalThrottledCount = 0;
+	private thermalKnownCount = 0;
+	private readonly thermalTransitions: ThermalTransition[] = [];
+
+	private lowPowerSampleCount = 0;
+	private lowPowerEver = false;
+	private lowPowerLast: boolean | null = null;
+	private lowPowerTransitions = 0;
+
+	constructor(private readonly opts: { leakGrowthMbThreshold?: number } = {}) {}
+
+	/** Record one generation's differenced throughput. */
+	recordGeneration(obs: GenerationObservation): void {
+		this.generations += 1;
+		if (isFiniteNumber(obs.prefillTokensPerSecond))
+			this.prefillHist.add(obs.prefillTokensPerSecond);
+		if (isFiniteNumber(obs.decodeTokensPerSecond))
+			this.decodeHist.add(obs.decodeTokensPerSecond);
+		if (isFiniteNumber(obs.combinedTokensPerSecond))
+			this.combinedHist.add(obs.combinedTokensPerSecond);
+		if (isFiniteNumber(obs.ttftMs)) this.ttftHist.add(obs.ttftMs);
+	}
+
+	/** Record one sampled device-resource snapshot. */
+	recordResourceSample(sample: ResourceSample): void {
+		this.resourceSamples += 1;
+
+		if (isFiniteNumber(sample.residentMemoryMb))
+			this.rssSamples.push(sample.residentMemoryMb);
+
+		if (isFiniteNumber(sample.batteryLevelPct)) {
+			const entry = { pct: sample.batteryLevelPct, atMs: sample.atMs };
+			if (this.firstBattery === null) this.firstBattery = entry;
+			this.lastBattery = entry;
+			this.batterySampleCount += 1;
+		}
+		if (isFiniteNumber(sample.batteryChargeMicroAmpHours)) {
+			if (this.firstChargeUah === null)
+				this.firstChargeUah = sample.batteryChargeMicroAmpHours;
+			this.lastChargeUah = sample.batteryChargeMicroAmpHours;
+		}
+		if (sample.isCharging === true) this.chargingObserved = true;
+
+		if (sample.thermalState != null) {
+			this.thermalSampleCount += 1;
+			if (this.thermalInitial === null)
+				this.thermalInitial = sample.thermalState;
+			const known = sample.thermalState !== "unknown";
+			if (known) {
+				this.thermalKnownCount += 1;
+				const rank =
+					THERMAL_RANK[
+						sample.thermalState as Exclude<DeviceThermalState, "unknown">
+					];
+				if (rank > this.thermalMaxRank) {
+					this.thermalMaxRank = rank;
+					this.thermalMaxState = sample.thermalState;
+				}
+				if (rank >= THERMAL_RANK.serious) this.thermalThrottledCount += 1;
+			}
+			if (
+				sample.thermalState !== this.thermalLast &&
+				this.thermalTransitions.length < MAX_THERMAL_TRANSITIONS
+			) {
+				this.thermalTransitions.push({
+					atMs: sample.atMs,
+					state: sample.thermalState,
+				});
+			}
+			this.thermalLast = sample.thermalState;
+		}
+
+		if (typeof sample.lowPowerMode === "boolean") {
+			this.lowPowerSampleCount += 1;
+			if (sample.lowPowerMode) this.lowPowerEver = true;
+			if (
+				this.lowPowerLast !== null &&
+				this.lowPowerLast !== sample.lowPowerMode
+			)
+				this.lowPowerTransitions += 1;
+			this.lowPowerLast = sample.lowPowerMode;
+		}
+	}
+
+	private rssSummary(): RssSummary {
+		const n = this.rssSamples.length;
+		const firstMb = n > 0 ? (this.rssSamples[0] as number) : null;
+		const lastMb = n > 0 ? (this.rssSamples[n - 1] as number) : null;
+		const peakMb = n > 0 ? Math.max(...this.rssSamples) : null;
+		// Steady state = median of the back half (excludes cold-load ramp).
+		const backHalf =
+			n >= 2 ? this.rssSamples.slice(Math.floor(n / 2)) : this.rssSamples;
+		const steadyMb = median(backHalf);
+		const growthMb =
+			firstMb !== null && lastMb !== null ? lastMb - firstMb : null;
+		const threshold = this.opts.leakGrowthMbThreshold ?? DEFAULT_LEAK_GROWTH_MB;
+		let monotone = n >= 4;
+		for (let i = 1; i < n; i++) {
+			if ((this.rssSamples[i] as number) < (this.rssSamples[i - 1] as number)) {
+				monotone = false;
+				break;
+			}
+		}
+		const leakSuspected = monotone && growthMb !== null && growthMb > threshold;
+		return {
+			firstMb,
+			lastMb,
+			peakMb,
+			steadyMb,
+			samples: n,
+			growthMb,
+			leakSuspected,
+		};
+	}
+
+	private batterySummary(): BatterySummary {
+		const firstPct = this.firstBattery?.pct ?? null;
+		const lastPct = this.lastBattery?.pct ?? null;
+		const drainPct =
+			firstPct !== null && lastPct !== null ? firstPct - lastPct : null;
+		const energyMicroAmpHoursDelta =
+			this.firstChargeUah !== null && this.lastChargeUah !== null
+				? this.firstChargeUah - this.lastChargeUah
+				: null;
+		const durationMs =
+			this.firstBattery !== null && this.lastBattery !== null
+				? this.lastBattery.atMs - this.firstBattery.atMs
+				: null;
+		return {
+			firstPct,
+			lastPct,
+			drainPct,
+			samples: this.batterySampleCount,
+			chargingObserved: this.chargingObserved,
+			energyMicroAmpHoursDelta,
+			durationMs,
+		};
+	}
+
+	private thermalSummary(): ThermalSummary {
+		const fractionThrottled =
+			this.thermalKnownCount > 0
+				? this.thermalThrottledCount / this.thermalKnownCount
+				: null;
+		return {
+			samples: this.thermalSampleCount,
+			initialState: this.thermalInitial,
+			maxState: this.thermalMaxState,
+			transitions: [...this.thermalTransitions],
+			transitionCount: Math.max(0, this.thermalTransitions.length - 1),
+			fractionThrottled,
+		};
+	}
+
+	summary(): DeviceResourceSummary {
+		return {
+			generations: this.generations,
+			resourceSamples: this.resourceSamples,
+			prefillTokensPerSecond: this.prefillHist.summary(),
+			decodeTokensPerSecond: this.decodeHist.summary(),
+			combinedTokensPerSecond: this.combinedHist.summary(),
+			ttftMs: this.ttftHist.summary(),
+			rss: this.rssSummary(),
+			battery: this.batterySummary(),
+			thermal: this.thermalSummary(),
+			lowPowerMode: {
+				samples: this.lowPowerSampleCount,
+				everEnabled: this.lowPowerEver,
+				transitionCount: this.lowPowerTransitions,
+			},
+		};
+	}
+}