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

package/src/services/network-policy.ts

@@ -0,0 +1,346 @@
+/**
+ * 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 {
+	applyNetworkPolicy,
+	classifyNetwork,
+	DEFAULT_NETWORK_POLICY_PREFERENCES,
+	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 function isHeadlessRuntime(): boolean {
+	if (process.env.ELIZA_NETWORK_POLICY === "headless") return true;
+	if (process.env.ELIZA_HEADLESS === "1") return true;
+	if (process.env.CI !== undefined && process.env.CI !== "false") return true;
+	if (typeof process.stdout.isTTY === "boolean" && !process.stdout.isTTY) {
+		// On a Linux server with no TTY this is a strong "headless" signal;
+		// but a packaged Electron app also has no TTY. Use the explicit env
+		// override above when we want to force one way or the other.
+		// Default: only headless when ALSO no DISPLAY / no Wayland session.
+		if (
+			process.platform === "linux" &&
+			!process.env.DISPLAY &&
+			!process.env.WAYLAND_DISPLAY
+		) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * 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 const NODE_DEFAULT_PROBE: NetworkProbe = {
+	id: "node-default",
+	async probe(): Promise<RawNetworkState> {
+		return { connectionType: "unknown", metered: null };
+	},
+};
+
+/**
+ * Headless probe — fires when `isHeadlessRuntime()` is true. The decision
+ * rule short-circuits to `headless-explicit-only` regardless of state.
+ */
+export const HEADLESS_PROBE: NetworkProbe = {
+	id: "headless",
+	async probe(): Promise<RawNetworkState> {
+		return { connectionType: "unknown", metered: null };
+	},
+};
+
+/**
+ * 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 function capacitorAndroidProbe(): NetworkProbe {
+	return {
+		id: "capacitor-android",
+		async probe(): Promise<RawNetworkState> {
+			const cap = readGlobalCapacitor();
+			const status = await cap?.Network?.getStatus?.();
+			const ctype: RawNetworkState["connectionType"] =
+				status?.connectionType === "wifi"
+					? "wifi"
+					: status?.connectionType === "cellular"
+						? "cellular"
+						: status?.connectionType === "none"
+							? "none"
+							: "unknown";
+			const meteredHint = await readAndroidMeteredShim();
+			return { connectionType: ctype, metered: meteredHint };
+		},
+	};
+}
+
+/**
+ * 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 function capacitorIosProbe(): NetworkProbe {
+	return {
+		id: "capacitor-ios",
+		async probe(): Promise<RawNetworkState> {
+			const cap = readGlobalCapacitor();
+			const status = await cap?.Network?.getStatus?.();
+			const ctype: RawNetworkState["connectionType"] =
+				status?.connectionType === "wifi"
+					? "wifi"
+					: status?.connectionType === "cellular"
+						? "cellular"
+						: status?.connectionType === "none"
+							? "none"
+							: "unknown";
+			const hints = await readIosPathHintsShim();
+			const metered = hints === null ? null : Boolean(hints.isExpensive);
+			return { connectionType: ctype, metered };
+		},
+	};
+}
+
+/**
+ * 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 function electronDesktopProbe(): NetworkProbe {
+	const detectId = (): NetworkProbe["id"] => {
+		if (process.platform === "darwin") return "electron-darwin";
+		if (process.platform === "win32") return "electron-win32";
+		return "electron-linux";
+	};
+	return {
+		id: detectId(),
+		async probe(): Promise<RawNetworkState> {
+			const bridge = readGlobalDesktopBridge();
+			if (!bridge) return { connectionType: "unknown", metered: null };
+			try {
+				const res = await bridge.networkPolicyProbe();
+				return {
+					connectionType: res.connectionType ?? "unknown",
+					metered: res.metered ?? null,
+				};
+			} catch {
+				return { connectionType: "unknown", metered: null };
+			}
+		},
+	};
+}
+
+interface CapacitorBridge {
+	Network?: {
+		getStatus?: () => Promise<{
+			connected?: boolean;
+			connectionType?: "wifi" | "cellular" | "none" | "unknown";
+		}>;
+	};
+}
+
+function readGlobalCapacitor(): CapacitorBridge | null {
+	const g = globalThis as {
+		Capacitor?: { Plugins?: CapacitorBridge };
+	};
+	return g.Capacitor?.Plugins ?? null;
+}
+
+interface AndroidMeteredShim {
+	getMeteredHint?: () => Promise<{ metered?: boolean }>;
+}
+interface IosPathHintsShim {
+	getPathHints?: () => Promise<{
+		isExpensive?: boolean;
+		isConstrained?: boolean;
+	}>;
+}
+
+async function readAndroidMeteredShim(): Promise<boolean | null> {
+	const g = globalThis as {
+		ElizaNetworkPolicy?: AndroidMeteredShim;
+	};
+	const fn = g.ElizaNetworkPolicy?.getMeteredHint;
+	if (typeof fn !== "function") return null;
+	try {
+		const res = await fn();
+		return typeof res.metered === "boolean" ? res.metered : null;
+	} catch {
+		return null;
+	}
+}
+
+async function readIosPathHintsShim(): Promise<{
+	isExpensive: boolean;
+	isConstrained: boolean;
+} | null> {
+	const g = globalThis as { ElizaNetworkPolicy?: IosPathHintsShim };
+	const fn = g.ElizaNetworkPolicy?.getPathHints;
+	if (typeof fn !== "function") return null;
+	try {
+		const res = await fn();
+		return {
+			isExpensive: Boolean(res.isExpensive),
+			isConstrained: Boolean(res.isConstrained),
+		};
+	} catch {
+		return null;
+	}
+}
+
+interface DesktopBridge {
+	networkPolicyProbe(): Promise<{
+		connectionType?: RawNetworkState["connectionType"];
+		metered?: boolean | null;
+	}>;
+}
+
+function readGlobalDesktopBridge(): DesktopBridge | null {
+	const g = globalThis as {
+		electrobunNative?: DesktopBridge;
+		electronAPI?: DesktopBridge;
+	};
+	return g.electrobunNative ?? g.electronAPI ?? null;
+}
+
+/**
+ * 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 function pickActiveProbe(): NetworkProbe {
+	if (isHeadlessRuntime()) return HEADLESS_PROBE;
+	const g = globalThis as {
+		Capacitor?: { getPlatform?: () => string };
+	};
+	const platform = g.Capacitor?.getPlatform?.();
+	if (platform === "android") return capacitorAndroidProbe();
+	if (platform === "ios") return capacitorIosProbe();
+	if (readGlobalDesktopBridge() !== null) return electronDesktopProbe();
+	return NODE_DEFAULT_PROBE;
+}
+
+/**
+ * High-level: probe + classify + apply prefs in one call. Used by the
+ * voice-model updater and by the local-inference download routes.
+ */
+export async function evaluateRuntimePolicy(args: {
+	prefs?: NetworkPolicyPreferences;
+	estimatedBytes: number;
+	probe?: NetworkProbe;
+	now?: Date;
+}): Promise<NetworkPolicyDecision> {
+	const probe = args.probe ?? pickActiveProbe();
+	const state = await probe.probe();
+	const klass = classifyNetwork(state);
+	const isHeadless = probe.id === "headless";
+	return applyNetworkPolicy(
+		klass,
+		args.prefs ?? DEFAULT_NETWORK_POLICY_PREFERENCES,
+		args.estimatedBytes,
+		{ now: args.now, isHeadless },
+	);
+}
+
+/** Surface for tests: full snapshot of the raw probe result + decision. */
+export async function describeRuntimeNetwork(args?: {
+	prefs?: NetworkPolicyPreferences;
+	estimatedBytes?: number;
+	probe?: NetworkProbe;
+	now?: Date;
+}): Promise<{
+	probeId: NetworkProbe["id"];
+	state: RawNetworkState;
+	class: NetworkClass;
+	decision: NetworkPolicyDecision;
+}> {
+	const probe = args?.probe ?? pickActiveProbe();
+	const state = await probe.probe();
+	const klass = classifyNetwork(state);
+	const estimatedBytes = args?.estimatedBytes ?? 0;
+	const isHeadless = probe.id === "headless";
+	const decision = applyNetworkPolicy(
+		klass,
+		args?.prefs ?? DEFAULT_NETWORK_POLICY_PREFERENCES,
+		estimatedBytes,
+		{ now: args?.now, isHeadless },
+	);
+	return { probeId: probe.id, state, class: klass, decision };
+}

package/src/services/paths.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { resolveStateDir } from "@elizaos/core";
+
+export function localInferenceRoot(): string {
+	return path.join(resolveStateDir(), "local-inference");
+}
+
+export function elizaModelsDir(): string {
+	return path.join(localInferenceRoot(), "models");
+}
+
+export function registryPath(): string {
+	return path.join(localInferenceRoot(), "registry.json");
+}
+
+export function downloadsStagingDir(): string {
+	return path.join(localInferenceRoot(), "downloads");
+}
+
+export function isWithinElizaRoot(target: string): boolean {
+	const root = path.resolve(localInferenceRoot());
+	const resolved = path.resolve(target);
+	if (resolved === root) return false;
+	return resolved.startsWith(`${root}${path.sep}`);
+}

package/src/services/planner-skeleton.ts

@@ -0,0 +1,175 @@
+/**
+ * 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,
+	buildPlannerActionGrammar,
+	buildPlannerParamsSkeleton,
+	type JSONSchema,
+	normalizeActionJsonSchema,
+	type ResponseSkeleton,
+} from "@elizaos/core";
+
+import {
+	type ElizaHarnessSchema,
+	elizaHarnessSchemaFromSkeleton,
+} 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 function buildPlanActionsSkeleton(
+	actions: ReadonlyArray<PlannerAction>,
+): ResponseSkeleton | null {
+	const result = buildPlannerActionGrammar(actions);
+	if (result === null) return null;
+	return result.responseSkeleton;
+}
+
+/**
+ * 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 function buildPlannerGuidedDecode(
+	actions: ReadonlyArray<PlannerAction>,
+): PlannerGuidedDecode | null {
+	const result = buildPlannerActionGrammar(actions);
+	if (result === null) return null;
+
+	const paramsSkeletons: Record<string, ResponseSkeleton> = {};
+	for (const action of actions) {
+		if (!action.name) continue;
+		paramsSkeletons[action.name] = buildPlannerParamsSkeleton(action);
+	}
+
+	const elizaSchema = elizaHarnessSchemaFromSkeleton({
+		skeleton: result.responseSkeleton,
+		grammar: result.grammar,
+	});
+
+	return {
+		responseSkeleton: result.responseSkeleton,
+		grammar: result.grammar,
+		actionSchemas: result.actionSchemas,
+		paramsSkeletons,
+		elizaSchema,
+	};
+}
+
+/**
+ * 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 function planActionParameterSchema(action: PlannerAction): JSONSchema {
+	return normalizeActionJsonSchema(action);
+}