@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/dist/services/memory-monitor.d.ts

@@ -0,0 +1,128 @@
+/**
+ * RAM-pressure monitor for the local-inference path (W10 / J2).
+ *
+ * Polls `os.freemem()` / `os.totalmem()` on an interval. When free RAM
+ * crosses a low-water threshold, the monitor walks the
+ * `SharedResourceRegistry`'s evictable model roles in *ascending priority*
+ * — `vision/mmproj < embedding < vad < ASR < TTS < text-target` —
+ * and evicts the cheapest one. Cheap evictions are the voice TTS/ASR weights
+ * (`MmapRegionHandle.evictPages()`), the vision projector, and unloading the
+ * embedding model. Every eviction is logged (observable) and reversible
+ * (roles re-load lazily on next use).
+ *
+ * The monitor never *loads* anything — it only frees memory. Re-load is the
+ * caller's job, on demand. It also never evicts the text target (priority
+ * 100) unless it's literally the only resident role and pressure persists,
+ * which is the intended "nothing left to give" behaviour.
+ *
+ * No fallback sludge: when there is nothing to evict and pressure persists,
+ * the monitor logs a warning and stops trying for a back-off window — it does
+ * not pretend it fixed anything.
+ */
+import type { ResidentModelRole, SharedResourceRegistry } from "./voice/shared-resources";
+/** Minimal structural logger — keeps this module dependency-free. */
+export interface MemoryMonitorLogger {
+    debug?(message: string): void;
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+export interface MemorySample {
+    totalMb: number;
+    freeMb: number;
+    /**
+     * Resident-set size in MB of the inference host. On the in-process FFI path
+     * this is the current process's RSS (`process.memoryUsage().rss`); the
+     * device-bridge path injects a phone-sourced figure. `null` only when no
+     * probe could read it.
+     */
+    serverRssMb: number | null;
+    /** Effective free memory used for the pressure decision (min of OS-free and total-minus-RSS-style headroom). */
+    effectiveFreeMb: number;
+    /** Free as a fraction of total (0..1), based on `effectiveFreeMb`. */
+    freeFraction: number;
+}
+export interface MemoryMonitorConfig {
+    /** Poll interval, ms. Default 30 s; min 1 s. */
+    intervalMs: number;
+    /**
+     * Evict when free RAM drops below `max(lowWaterMb, lowWaterFraction*total)`.
+     * Defaults: 768 MB / 8% of total.
+     */
+    lowWaterMb: number;
+    lowWaterFraction: number;
+    /**
+     * After an eviction, wait this long before the next eviction so the OS
+     * has time to reflect the reclaimed pages. Default 5 s.
+     */
+    evictionCooldownMs: number;
+    /**
+     * After "nothing left to evict", back off for this long before warning
+     * again. Default 60 s.
+     */
+    exhaustedBackoffMs: number;
+}
+export declare function resolveMemoryMonitorConfig(overrides?: Partial<MemoryMonitorConfig>): MemoryMonitorConfig;
+/** Pluggable sources so the monitor stays unit-testable without OS state. */
+export interface MemoryMonitorSources {
+    /**
+     * Available/total memory in bytes. Defaults to `readSystemMemory()`
+     * (`/proc/meminfo` `MemAvailable` on Linux/Android, `os.freemem()` elsewhere).
+     */
+    osMemory?: () => {
+        freeBytes: number;
+        totalBytes: number;
+    };
+    /** Running external runtime RSS in MB, or null. */
+    serverRssMb?: () => Promise<number | null>;
+}
+export interface MemoryPressureAction {
+    sample: MemorySample;
+    /** What got evicted this tick, if anything. */
+    evicted: {
+        id: string;
+        role: ResidentModelRole;
+        estimatedMb: number;
+    } | null;
+    /** True when pressure was detected but nothing could be evicted. */
+    exhausted: boolean;
+    /**
+     * True when pressure was detected but eviction was deferred to the registry's
+     * external eviction owner (the `MemoryArbiter`) so the two loops never
+     * double-evict on one pressure event (#8809 AC#2).
+     */
+    delegated?: boolean;
+}
+export declare class MemoryMonitor {
+    private readonly config;
+    private readonly registry;
+    private readonly log?;
+    private readonly osMemory;
+    private readonly serverRssMb;
+    private timer;
+    private ticking;
+    private lastEvictionAtMs;
+    private exhaustedUntilMs;
+    constructor(args: {
+        registry: SharedResourceRegistry;
+        config?: Partial<MemoryMonitorConfig>;
+        logger?: MemoryMonitorLogger;
+        sources?: MemoryMonitorSources;
+    });
+    /** Begin polling. Idempotent. The interval is unref'd so it never holds the process open. */
+    start(): void;
+    stop(): void;
+    /** Whether the polling timer is running. */
+    isRunning(): boolean;
+    /** Take a memory sample now (no side effects). */
+    sample(): Promise<MemorySample>;
+    /** Low-water line for the current sample, in MB. */
+    private lowWaterMb;
+    isUnderPressure(sample: MemorySample): boolean;
+    /**
+     * One monitor step: sample, and if under pressure (and not in cooldown),
+     * evict the lowest-priority resident role. Returns what it did so callers
+     * (and tests) can assert. Public so tests don't have to wait on a timer.
+     */
+    tick(now?: number): Promise<MemoryPressureAction>;
+}
+//# sourceMappingURL=memory-monitor.d.ts.map

package/dist/services/memory-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.d.ts","sourceRoot":"","sources":["../../src/services/memory-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACX,iBAAiB,EACjB,sBAAsB,EACtB,MAAM,0BAA0B,CAAC;AAElC,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IACnC,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gHAAgH;IAChH,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AA4BD,wBAAgB,0BAA0B,CACzC,SAAS,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC1C,mBAAmB,CA0BrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,iBAAiB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7E,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;IAC3E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,IAAI,EAAE;QACjB,QAAQ,EAAE,sBAAsB,CAAC;QACjC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,mBAAmB,CAAC;QAC7B,OAAO,CAAC,EAAE,oBAAoB,CAAC;KAC/B;IASD,6FAA6F;IAC7F,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;IAOZ,4CAA4C;IAC5C,SAAS,IAAI,OAAO;IAIpB,kDAAkD;IAC5C,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAuBrC,oDAAoD;IACpD,OAAO,CAAC,UAAU;IAOlB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAI9C;;;;OAIG;IACG,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA0CnE"}

package/dist/services/memory-pressure.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Cross-platform memory-pressure sources for the Memory Arbiter (WS1).
+ *
+ * The arbiter consumes a `MemoryPressureSource` interface so it doesn't
+ * care whether the signal comes from polling `os.freemem()`, an Android
+ * `ComponentCallbacks2.onTrimMemory()` callback, or an iOS
+ * `UIApplicationDidReceiveMemoryWarningNotification` subscription.
+ *
+ * Three concrete implementations live here:
+ *
+ *   1. `nodeOsPressureSource` — desktop / server. Polls `os.freemem()` /
+ *      `os.totalmem()` on a fixed cadence (~5 s). Emits `nominal` /
+ *      `low` / `critical` from a two-threshold high-water mark over total
+ *      RAM. The polling timer is `unref`'d so it never holds the process
+ *      open.
+ *
+ *   2. `capacitorPressureSource` — Capacitor iOS/Android shim. The native
+ *      side (Android `ComponentCallbacks2.onTrimMemory`, iOS
+ *      `UIApplicationDidReceiveMemoryWarningNotification`) calls
+ *      `dispatch(level)` via the bridge, which fans the level out to
+ *      arbiter listeners. The JS contract is fixed here; the native
+ *      modules will be wired in WS2 / WS8.
+ *
+ *   3. `compositePressureSource` — combine sources (e.g. one OS poll +
+ *      one Capacitor bridge). The composite emits the *worst* reported
+ *      level so neither signal can mask the other.
+ *
+ * Pressure semantics — what each level means to the arbiter:
+ *   - `nominal`  → no action; the arbiter may load freely.
+ *   - `low`      → the arbiter SHOULD evict the lowest-priority resident
+ *                   role and may pause optimistic preloads.
+ *   - `critical` → the arbiter MUST evict every non-text-target role
+ *                   immediately; `acquire()` for non-text capabilities is
+ *                   allowed to throw.
+ *
+ * No fallback sludge:
+ *   - When a probe fails (e.g. `os.freemem()` returns NaN under sandboxing),
+ *     the source emits `nominal` and logs a warning. It does NOT pretend
+ *     the system is critical and start trashing models.
+ *   - `dispatch(level)` from a native bridge is trusted; the JS layer does
+ *     not second-guess it with its own poll.
+ */
+/** Pressure level the arbiter consumes. */
+export type MemoryPressureLevel = "nominal" | "low" | "critical";
+export interface MemoryPressureEvent {
+    level: MemoryPressureLevel;
+    /** Optional free RAM, MB. Present for poll-based sources; absent for OS-callback bridges. */
+    freeMb?: number;
+    /** Optional total RAM, MB. */
+    totalMb?: number;
+    /** Free as a fraction of total (0..1). Present when both above are present. */
+    freeFraction?: number;
+    /** Source identifier — handy for telemetry. `os-poll` / `capacitor` / `composite`. */
+    source: string;
+    /** Wall-clock ms when the event was generated. */
+    atMs: number;
+}
+export type MemoryPressureListener = (event: MemoryPressureEvent) => void;
+export interface MemoryPressureSource {
+    /** Stable identifier for the source (used in telemetry tags). */
+    readonly id: string;
+    /** Subscribe to pressure events. Returns the unsubscribe fn. */
+    subscribe(listener: MemoryPressureListener): () => void;
+    /** Begin observing. Idempotent. */
+    start(): void;
+    /** Stop observing. Idempotent. */
+    stop(): void;
+    /** Take a one-shot reading without subscribing. May reuse the cached level. */
+    current(): MemoryPressureEvent;
+}
+export interface NodeOsPressureConfig {
+    /** Poll interval, ms. Default 5000 (5 s); min 500 ms. */
+    intervalMs: number;
+    /**
+     * Below this fraction of total RAM, level becomes `low`. Default 0.15.
+     */
+    lowWaterFraction: number;
+    /**
+     * Below this fraction of total RAM, level becomes `critical`. Default 0.05.
+     * Must be < lowWaterFraction; the source enforces this at construction.
+     */
+    criticalWaterFraction: number;
+    /** Optional injected clock (testing). Defaults to `Date.now()`. */
+    now?: () => number;
+}
+export interface NodeOsPressureSources {
+    /**
+     * Available/total memory in bytes. Defaults to `readSystemMemory()`
+     * (`/proc/meminfo` `MemAvailable` on Linux/Android, `os.freemem()` elsewhere).
+     */
+    osMemory?: () => {
+        freeBytes: number;
+        totalBytes: number;
+    };
+    /** Optional logger; warnings only. */
+    logger?: {
+        warn?: (m: string) => void;
+    };
+}
+/**
+ * Polling pressure source for desktop/server. The poll happens on an
+ * `unref`'d timer so the process can exit naturally. Listeners only fire
+ * when the level *changes* (or the first time after `start()`); raw
+ * readings are still available via `current()` for logging.
+ */
+export declare function nodeOsPressureSource(overrides?: Partial<NodeOsPressureConfig>, sources?: NodeOsPressureSources): MemoryPressureSource;
+/**
+ * Capacitor-side bridge. The native module dispatches a level whenever
+ * the OS hands it a memory-pressure callback (Android: `onTrimMemory`,
+ * mapping `TRIM_MEMORY_RUNNING_LOW`/`TRIM_MEMORY_RUNNING_CRITICAL` to
+ * `low`/`critical`; iOS: `didReceiveMemoryWarning` → `critical`). The JS
+ * surface is `dispatch(level, freeMb?)`. The host wires this to the
+ * Capacitor plugin in WS2/WS8; here we own the contract + JS state.
+ */
+export interface CapacitorPressureSource extends MemoryPressureSource {
+    /** Called by the Capacitor native bridge whenever the OS signals pressure. */
+    dispatch(level: MemoryPressureLevel, freeMb?: number): void;
+}
+export declare function capacitorPressureSource(opts?: {
+    now?: () => number;
+}): CapacitorPressureSource;
+/**
+ * Combine multiple sources. Subscribers see the *worst* level reported by
+ * any underlying source — once a critical signal arrives, the composite
+ * stays critical until every source returns to nominal/low.
+ */
+export declare function compositePressureSource(sources: ReadonlyArray<MemoryPressureSource>, opts?: {
+    now?: () => number;
+}): MemoryPressureSource;
+//# sourceMappingURL=memory-pressure.d.ts.map

package/dist/services/memory-pressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-pressure.d.ts","sourceRoot":"","sources":["../../src/services/memory-pressure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,2CAA2C;AAC3C,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACpC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAAC;IACxD,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;IACd,kCAAkC;IAClC,IAAI,IAAI,IAAI,CAAC;IACb,+EAA+E;IAC/E,OAAO,IAAI,mBAAmB,CAAC;CAC/B;AAID,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,sCAAsC;IACtC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACxC;AAQD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,EAC7C,OAAO,GAAE,qBAA0B,GACjC,oBAAoB,CAyGtB;AAQD;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACpE,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5D;AAED,wBAAgB,uBAAuB,CACtC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAC/B,uBAAuB,CAoDzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,EAC5C,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAiGtB"}

package/dist/services/mtp-doctor.d.ts

@@ -0,0 +1,13 @@
+export type MtpDoctorCheckStatus = "pass" | "warn" | "fail";
+export interface MtpDoctorCheck {
+    label: string;
+    status: MtpDoctorCheckStatus;
+    detail: string;
+    fix?: string;
+}
+export interface MtpDoctorReport {
+    ok: boolean;
+    checks: MtpDoctorCheck[];
+}
+export declare function runMtpDoctor(): Promise<MtpDoctorReport>;
+//# sourceMappingURL=mtp-doctor.d.ts.map

package/dist/services/mtp-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtp-doctor.d.ts","sourceRoot":"","sources":["../../src/services/mtp-doctor.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,cAAc,EAAE,CAAC;CACzB;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC,CAgE7D"}

package/dist/services/network-policy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * NetworkPolicy bridge for `plugin-local-inference` (R5-versioning §4).
+ *
+ * The shared module `@elizaos/shared/local-inference/network-policy` defines
+ * the platform-agnostic classifier + decision rule. This module wires the
+ * platform-specific probes:
+ *
+ * - **Android** (Capacitor / AOSP runtime): `@capacitor/network`'s
+ *   `Network.getStatus()` for connection type, plus an explicit native
+ *   shim (`getMeteredHint`) that reads `NetworkCapabilities.hasCapability(
+ *   NET_CAPABILITY_NOT_METERED)`. Android docs explicitly warn against
+ *   equating "cellular" with "metered" — the metered flag is mandatory.
+ * - **iOS** (Capacitor / native): `@capacitor/network` for connection type
+ *   plus our native bridge that reads `NWPathMonitor.path.isExpensive`.
+ *   `isExpensive == true` is Apple's "treat as metered" flag.
+ * - **Desktop** (Electron/Electrobun): platform-specific OS shims —
+ *   WinRT `NetworkCostType` on Windows, NetworkManager dbus
+ *   `ActiveConnection.Metered` on Linux, `NWPathMonitor` on macOS.
+ *   When no shim is available, falls back to `metered: false` on a wired
+ *   link and `metered: null` (unknown) on Wi-Fi; the policy turns
+ *   `unknown` into `ask` so the user is never surprised.
+ * - **Headless server / CLI** (`ELIZA_NETWORK_POLICY=headless` or
+ *   `process.stdout.isTTY === false && process.env.CI !== undefined`):
+ *   skip auto-update entirely. The `eliza models update` CLI invocation
+ *   still works, but the runtime tick is silent.
+ *
+ * The Capacitor / native bridges that hook into the global `window`
+ * object on mobile are installed by the AOSP / iOS plugin layers; this
+ * module reads them through an injectable adapter so the server-side
+ * runtime stays platform-pure and tests can drive the state machine
+ * without any of the native dependencies.
+ *
+ * Spec: `.swarm/research/R5-versioning.md` §4.
+ */
+import { type NetworkClass, type NetworkPolicyDecision, type NetworkPolicyPreferences, type RawNetworkState } from "@elizaos/shared";
+/**
+ * Platform probe — produces a `RawNetworkState` from whatever OS API is
+ * available. Each platform shim implements this; the registry below picks
+ * the active one at runtime.
+ */
+export interface NetworkProbe {
+    readonly id: "node-default" | "capacitor-android" | "capacitor-ios" | "electron-darwin" | "electron-win32" | "electron-linux" | "headless";
+    probe(): Promise<RawNetworkState>;
+}
+/**
+ * Heuristic: are we running headless (no TTY, in CI, or with an explicit
+ * override)? Headless callers should NOT auto-update because there is no
+ * one around to confirm a multi-GB download.
+ */
+export declare function isHeadlessRuntime(): boolean;
+/**
+ * Default Node probe — returns `unknown` for everything. Useful in tests
+ * and on packaged servers where there is no Capacitor / Electron bridge.
+ * The policy will downgrade `unknown` to `ask`, which is correct for the
+ * platform-uncertain case.
+ */
+export declare const NODE_DEFAULT_PROBE: NetworkProbe;
+/**
+ * Headless probe — fires when `isHeadlessRuntime()` is true. The decision
+ * rule short-circuits to `headless-explicit-only` regardless of state.
+ */
+export declare const HEADLESS_PROBE: NetworkProbe;
+/**
+ * Capacitor Android probe (R5 §4.1).
+ *
+ * Reads connection type from `@capacitor/network` and metered status from
+ * a native shim exposed at `(window as any).ElizaNetworkPolicy` (provided
+ * by the `@elizaos/capacitor-network-policy` Capacitor plugin at
+ * `plugins/plugin-native-network-policy/`). Importing the plugin from
+ * the app bootstrap installs `globalThis.ElizaNetworkPolicy` via the
+ * plugin's `installNetworkPolicyGlobal()` side-effect, so the runtime
+ * picks it up automatically. When the shim is missing the metered flag
+ * falls back to `null` (= unknown), which triggers `ask` per R5 §4.1.
+ */
+export declare function capacitorAndroidProbe(): NetworkProbe;
+/**
+ * Capacitor iOS probe (R5 §4.2). Connection type from `@capacitor/network`
+ * plus iOS `NWPathMonitor.currentPath.isExpensive` via the
+ * `@elizaos/capacitor-network-policy` Capacitor plugin at
+ * `plugins/plugin-native-network-policy/`. The plugin exposes
+ * `(window as any).ElizaNetworkPolicy.getPathHints()`; falls back to
+ * `metered: null` when the bridge is missing.
+ */
+export declare function capacitorIosProbe(): NetworkProbe;
+/**
+ * Electron / desktop probe. Calls into a process-bridge-exposed function
+ * (Electrobun: `Bun.napi`/`electrobunNative.networkPolicyProbe`; classic
+ * Electron: `electronAPI.networkPolicyProbe`) that wraps the OS call.
+ * Returns `unknown` when no bridge is wired (development-mode browser
+ * preview), which downgrades to `ask` on `wifi-*` and `auto` on
+ * `ethernet-unmetered` per the matrix.
+ */
+export declare function electronDesktopProbe(): NetworkProbe;
+/**
+ * Pick the active probe based on platform heuristics. Order:
+ *
+ * 1. `ELIZA_NETWORK_POLICY=headless` (or CI / no-TTY-no-DISPLAY) → headless.
+ * 2. Capacitor android bridge present → Android probe.
+ * 3. Capacitor iOS bridge present → iOS probe (`process.platform` !==
+ *    `android` and a `Capacitor` global exists).
+ * 4. Desktop bridge present → desktop probe.
+ * 5. Otherwise → node-default (returns `unknown`).
+ */
+export declare function pickActiveProbe(): NetworkProbe;
+/**
+ * High-level: probe + classify + apply prefs in one call. Used by the
+ * voice-model updater and by the local-inference download routes.
+ */
+export declare function evaluateRuntimePolicy(args: {
+    prefs?: NetworkPolicyPreferences;
+    estimatedBytes: number;
+    probe?: NetworkProbe;
+    now?: Date;
+}): Promise<NetworkPolicyDecision>;
+/** Surface for tests: full snapshot of the raw probe result + decision. */
+export declare function describeRuntimeNetwork(args?: {
+    prefs?: NetworkPolicyPreferences;
+    estimatedBytes?: number;
+    probe?: NetworkProbe;
+    now?: Date;
+}): Promise<{
+    probeId: NetworkProbe["id"];
+    state: RawNetworkState;
+    class: NetworkClass;
+    decision: NetworkPolicyDecision;
+}>;
+//# sourceMappingURL=network-policy.d.ts.map

package/dist/services/network-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-policy.d.ts","sourceRoot":"","sources":["../../src/services/network-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,MAAM,iBAAiB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,EAAE,EACR,cAAc,GACd,mBAAmB,GACnB,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,UAAU,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAkB3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,YAKhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,YAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,IAAI,YAAY,CAkBpD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAmBhD;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,CAsBnD;AA2ED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IACjD,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,GAAG,CAAC,EAAE,IAAI,CAAC;CACX,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAWjC;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE;IACnD,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,GAAG,CAAC,EAAE,IAAI,CAAC;CACX,GAAG,OAAO,CAAC;IACX,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,qBAAqB,CAAC;CAChC,CAAC,CAaD"}

package/dist/services/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function localInferenceRoot(): string;
+export declare function elizaModelsDir(): string;
+export declare function registryPath(): string;
+export declare function downloadsStagingDir(): string;
+export declare function isWithinElizaRoot(target: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/services/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/services/paths.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKzD"}

package/dist/services/planner-skeleton.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Planner (`PLAN_ACTIONS`) skeleton + GBNF wiring for the local-inference
+ * stage.
+ *
+ * The response-handler stage is already constrained — `shouldRespond` is a
+ * three-value enum that the lazy GBNF pins (see
+ * `packages/core/src/runtime/builtin-field-evaluators.ts`). The planner
+ * stage, however, has historically emitted `PLAN_ACTIONS({...})` calls
+ * unconstrained for local backends: the model could hallucinate action
+ * names, drop required parameters, or invent free-form parameter values
+ * outside the registered enum.
+ *
+ * This module is the local-inference-side surface for the same guided-decode
+ * contract the response handler uses:
+ *
+ *   1. `buildPlanActionsSkeleton(actions)` — top-level envelope skeleton
+ *      `{"action": <enum>, "parameters": <free-json>, "thought": <free-string>}`.
+ *      `action` is pinned to the alternation of registered action names and
+ *      collapses to a literal when only one action is exposed.
+ *
+ *   2. `buildPlannerGuidedDecode(actions)` — the full bundle: the skeleton
+ *      above, the precise GBNF (`@elizaos/core`'s `buildPlannerActionGrammar`
+ *      emits one that also pins the array-element enum), and per-action
+ *      `parameters` schemas + sub-skeletons for the engine's optional second
+ *      pass once `action` is committed.
+ *
+ * Why this lives in app-core (not core): the helper is meaningful only to
+ * the local-inference layer — cloud adapters can satisfy the portable `tools`
+ * contract without honoring `responseSkeleton` / `grammar`. Keeping the
+ * wrapper here makes the local-only nature explicit at the import site and
+ * pins the test surface (`__tests__/planner-grammar.test.ts`) next to the
+ * engine that consumes the output.
+ *
+ * GBNF compiler limitation: `compileSkeletonToGbnf` cannot express
+ * per-action parameter discrimination in a single flat skeleton (the spans
+ * are positional; there's no anyOf-with-discriminator branch). We therefore
+ * fall back to the documented two-pass shape — top-level skeleton pins
+ * `action`, the engine drives a second constrained pass against the chosen
+ * action's normalized JSON schema. `buildPlannerParamsSkeleton` (re-exported
+ * from `@elizaos/core`) provides the per-action sub-skeleton.
+ */
+import { type Action, type JSONSchema, type ResponseSkeleton } from "@elizaos/core";
+import { type ElizaHarnessSchema } from "./structured-output";
+/**
+ * The minimal shape this module consumes from an `Action`. Accepting the
+ * structural pick keeps the helper testable in isolation (no handlers /
+ * validators need test doubles).
+ */
+export type PlannerAction = Pick<Action, "name" | "parameters" | "allowAdditionalParameters">;
+/**
+ * Bundle of the structure-forcing artefacts the local-inference engine needs
+ * to constrain a `PLAN_ACTIONS` generation.
+ */
+export interface PlannerGuidedDecode {
+    /**
+     * Top-level skeleton: `{"action": <enum>, "parameters": <free-json>,
+     * "thought": <free-string>}`. Compiles to a lazy GBNF via
+     * `compileSkeletonToGbnf` — `action` is the alternation of registered
+     * action names (or a literal when only one action is exposed).
+     */
+    responseSkeleton: ResponseSkeleton;
+    /**
+     * Pre-built GBNF for the top-level envelope. Wins over compiling the
+     * skeleton (the explicit grammar carries the same alternation as the
+     * skeleton's enum span — they are byte-equivalent — but the explicit
+     * grammar is what the cloud-mirroring code path in
+     * `@elizaos/core`'s `buildPlannerActionGrammar` already produces).
+     */
+    grammar: string;
+    /**
+     * Map of action name → normalized JSON Schema for its `parameters` object.
+     * The engine uses this for the optional second constrained pass once
+     * `action` is committed. Cloud adapters ignore it; tools carry the
+     * equivalent (unforced) contract for them.
+     */
+    actionSchemas: Record<string, JSONSchema>;
+    /**
+     * Per-action `parameters` skeleton (single-value enums collapse to
+     * literals; multi-value enums stay as enum spans). Keyed by action name.
+     * Engines may compile each entry on demand for the second pass.
+     */
+    paramsSkeletons: Record<string, ResponseSkeleton>;
+    /**
+     * Eliza harness schema for the top-level envelope — the bundle of
+     * skeleton + grammar + derived prefill plan. Pass this on
+     * {@link StructuredGenerateParams.elizaSchema} to engage the
+     * deterministic-token prefill-plan fast-forward on top of the GBNF
+     * constrained decode.
+     */
+    elizaSchema: ElizaHarnessSchema;
+}
+/**
+ * Build the top-level `PLAN_ACTIONS` envelope skeleton from the action set
+ * exposed this turn.
+ *
+ * Shape:
+ *   `{"action": <enum>, "parameters": <free-json>, "thought": <free-string>}`
+ *
+ * Returns `null` when no actions are exposed (caller should skip
+ * structure-forcing — there is nothing to constrain `action` to).
+ *
+ * GBNF compiler limitation: `compileSkeletonToGbnf` does not support
+ * anyOf-with-discriminator in a single skeleton — the per-action parameter
+ * shape cannot be expressed positionally. The engine drives a second
+ * constrained pass against {@link PlannerGuidedDecode.actionSchemas} /
+ * {@link PlannerGuidedDecode.paramsSkeletons} once `action` is committed.
+ */
+export declare function buildPlanActionsSkeleton(actions: ReadonlyArray<PlannerAction>): ResponseSkeleton | null;
+/**
+ * Build the full guided-decode bundle for a `PLAN_ACTIONS` generation: the
+ * top-level skeleton, the precise GBNF, the per-action parameter schemas,
+ * and the per-action `parameters` sub-skeletons.
+ *
+ * Returns `null` when no actions are exposed.
+ */
+export declare function buildPlannerGuidedDecode(actions: ReadonlyArray<PlannerAction>): PlannerGuidedDecode | null;
+/**
+ * Convenience: normalize a single action's `parameters` to a core
+ * {@link JSONSchema}. Re-exported here so callers staying inside the
+ * local-inference module can build per-action constraints without
+ * pulling `@elizaos/core/runtime/...`.
+ */
+export declare function planActionParameterSchema(action: PlannerAction): JSONSchema;
+//# sourceMappingURL=planner-skeleton.d.ts.map

package/dist/services/planner-skeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-skeleton.d.ts","sourceRoot":"","sources":["../../src/services/planner-skeleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EACN,KAAK,MAAM,EAGX,KAAK,UAAU,EAEf,KAAK,gBAAgB,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACN,KAAK,kBAAkB,EAEvB,MAAM,qBAAqB,CAAC;AAE7B;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,MAAM,EACN,MAAM,GAAG,YAAY,GAAG,2BAA2B,CACnD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC1C;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,WAAW,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,GACnC,gBAAgB,GAAG,IAAI,CAIzB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,GACnC,mBAAmB,GAAG,IAAI,CAsB5B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAE3E"}

package/dist/services/providers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Provider registry.
+ *
+ * Treats every inference source the same way — cloud subscription, cloud
+ * API, Eliza-1 local runtime, paired-device bridge, Capacitor on-device
+ * — each is a `ProviderDefinition` with an `id`, a human label, a set of
+ * supported model slots, and a pluggable `getEnableState()` that inspects
+ * whatever underlying gate controls it (API key presence, subscription
+ * status, env flag, file on disk).
+ *
+ * The cloud-provider status readers are intentionally permissive: they
+ * report what they can introspect without depending on the specific
+ * cloud-plugin internals, and hand off to the existing ProviderSwitcher
+ * UI for actual enable/disable via `configureHref`. That avoids the
+ * "combined enable matrix is an architectural project" problem by making
+ * configuration navigable rather than centralised.
+ */
+import type { ProviderEnableState, ProviderId, ProviderMeta, ProviderStatus } from "@elizaos/shared";
+/**
+ * Runtime provider descriptor. Extends the UI-safe `ProviderMeta` with a
+ * callable `getEnableState()` that inspects env vars, fs, or device-bridge
+ * sockets. Server-side only — UI code reads `ProviderMeta` /
+ * `ProviderStatus` from `@elizaos/shared` instead.
+ */
+export interface ProviderDefinition extends ProviderMeta {
+    /**
+     * Read the current enable state. For cloud providers we inspect env
+     * vars or config fragments; for local we check file presence; for
+     * device-bridge we check connected-device count.
+     */
+    getEnableState(): Promise<ProviderEnableState>;
+}
+export type { ProviderEnableState, ProviderId, ProviderMeta, ProviderStatus };
+/** Resolve which slots have at least one registered handler from this provider. */
+export declare function getRegisteredSlotsForProvider(providerId: string): string[];
+export declare const BUILT_IN_PROVIDERS: readonly ProviderDefinition[];
+export declare function snapshotProviders(): Promise<ProviderStatus[]>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/services/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/services/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACX,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,MAAM,iBAAiB,CAAC;AAKzB;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC/C;AAED,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE9E,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAO1E;AA+UD,eAAO,MAAM,kBAAkB,EAAE,SAAS,kBAAkB,EAoB3D,CAAC;AAgFF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAiBnE"}