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

package/src/services/inference-capabilities.ts

@@ -0,0 +1,204 @@
+/**
+ * Inference capability detection.
+ *
+ * Centralises "what does this device's local-inference stack expose"
+ * into one struct the runtime can read at startup.  The shape mirrors
+ * the per-platform binding probes (Android + iOS + desktop FFI) so the
+ * runtime doesn't have to import each platform's adapter just to
+ * surface the bits.
+ *
+ * Consumed by:
+ *   - the AOSP local-inference bootstrap, to choose the in-process FFI
+ *     streaming path,
+ *   - the desktop voice lifecycle service, to decide whether to wire the
+ *     FFI streaming runner factory,
+ *   - UI surfaces (model picker, voice toggle) that hide options the
+ *     loaded build cannot honour.
+ *
+ * Naming:
+ *   - `streamingLlm` — `eliza_inference_llm_stream_*` symbols are
+ *     resolved and the build reports `_supported() === 1`.
+ *   - `mtpSupported` — native MTP speculative decoding can actually run.
+ *   - `omnivoiceStreaming` — `eliza_inference_tts_synthesize_stream` is
+ *     present and supported.
+ *   - `mmprojSupported` — the build carries the multi-modal projector
+ *     and the device has the headroom to keep it resident.
+ *   - `thermalState` — best-effort current thermal snapshot from the
+ *     platform (`ProcessInfo.thermalState` on iOS,
+ *     `PowerManager.getCurrentThermalStatus` on Android).
+ *
+ * All fields are read-only snapshots; the runtime re-probes on resume.
+ */
+
+export type ThermalState = "nominal" | "fair" | "serious" | "critical";
+
+export interface InferenceCapabilities {
+	streamingLlm: boolean;
+	mtpSupported: boolean;
+	omnivoiceStreaming: boolean;
+	mmprojSupported: boolean;
+	thermalState: ThermalState;
+	/** Platform tag for diagnostics + routing. */
+	platform: "android" | "ios" | "desktop" | "unknown";
+}
+
+/** Minimal probe surface — what the caller hands in. */
+export interface CapabilityProbes {
+	/** True only when `eliza_inference_llm_stream_supported()` returns 1. */
+	llmStreamSupported(): boolean;
+	/** True only when `eliza_inference_tts_stream_supported()` returns 1. */
+	ttsStreamSupported(): boolean;
+	/** True only when the native MTP path is available for the loaded model. */
+	mtpResident(): boolean;
+	/** True only when the mmproj weights are present in the bundle. */
+	mmprojResident(): boolean;
+	/** Current thermal snapshot.  May return `nominal` on platforms without a thermal API. */
+	thermalState(): ThermalState;
+	/** Platform tag. */
+	platform(): "android" | "ios" | "desktop" | "unknown";
+}
+
+/**
+ * Build a capability struct from a set of probes.
+ *
+ * Policy decisions encoded here:
+ *   - Native MTP only fires when `llmStreamSupported` and the thermal state is
+ *     at most `fair`.
+ *   - mmproj is gated entirely on the bundle carrying it.  Devices
+ *     short on RAM can still load the chat model — they just lose the
+ *     vision path; the picker UI uses this bit to grey out vision
+ *     uploads.
+ *   - omnivoice streaming is gated entirely on the FFI build: the JS
+ *     side has no fallback path for streaming TTS, only for batch.
+ */
+export function probeCapabilities(
+	probes: CapabilityProbes,
+): InferenceCapabilities {
+	const streamingLlm = probes.llmStreamSupported();
+	const omnivoiceStreaming = probes.ttsStreamSupported();
+	const mtpResident = probes.mtpResident();
+	const mmprojResident = probes.mmprojResident();
+	const thermalState = probes.thermalState();
+	const platform = probes.platform();
+
+	const thermalBlocksMtp =
+		thermalState === "serious" || thermalState === "critical";
+
+	const mtpSupported = streamingLlm && mtpResident && !thermalBlocksMtp;
+
+	return {
+		streamingLlm,
+		mtpSupported,
+		omnivoiceStreaming,
+		mmprojSupported: mmprojResident,
+		thermalState,
+		platform,
+	};
+}
+
+/**
+ * Defaults probe: every flag off, platform `unknown`, thermal `nominal`.
+ * Used by the runtime when no FFI binding could be loaded (cloud-only
+ * fallback path).  Surfaces as a single struct the UI can render
+ * without branching on "no probe registered".
+ */
+export function defaultsForNoBinding(): InferenceCapabilities {
+	return {
+		streamingLlm: false,
+		mtpSupported: false,
+		omnivoiceStreaming: false,
+		mmprojSupported: false,
+		thermalState: "nominal",
+		platform: "unknown",
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Sampled resource snapshot + thermal-throttle decision
+// ---------------------------------------------------------------------------
+
+/**
+ * A live, *sampled* device-resource snapshot from the native probe
+ * (iOS `getResourceSnapshot`, Android `ResourceProbe.getResourceSnapshot`) — as
+ * opposed to the one-shot `InferenceCapabilities` probe. The Mobile Resource
+ * Workbench (issue #8800) samples these on an interval across a sustained
+ * workload to build a thermal/RSS/battery timeline. Every numeric field is
+ * `null` when the platform could not measure it — never a fabricated zero.
+ */
+export interface ResourceSnapshot {
+	/** Current thermal state; `"unknown"` on platforms without a thermal API. */
+	thermalState: ThermalState | "unknown";
+	/** Whether the OS low-power / battery-saver mode is engaged, or null. */
+	lowPowerMode: boolean | null;
+	/** Process resident set size in MB, or null. */
+	residentMemoryMb: number | null;
+	/** Device-wide available RAM in MB, or null. */
+	availableRamMb: number | null;
+	/** Cumulative process CPU time in ms, or null. */
+	cpuTimeMs: number | null;
+	/** Battery level 0..100, or null. */
+	batteryLevelPct: number | null;
+	/** Sample timestamp in ms (epoch). */
+	capturedAtMs: number;
+}
+
+export interface ThermalThrottleDecision {
+	/**
+	 * Whether speculative decoding (MTP) should be disabled for the next step.
+	 * MTP burns extra compute for a latency win; under heat that trade flips.
+	 */
+	throttleSpeculativeDecode: boolean;
+	/**
+	 * Whether to proactively shed load (shrink batch / context, pause warmups)
+	 * because the device is at the top of the thermal range.
+	 */
+	reduceLoad: boolean;
+	reason: string;
+}
+
+const THROTTLE_SEVERITY: Record<ThermalState, number> = {
+	nominal: 0,
+	fair: 1,
+	serious: 2,
+	critical: 3,
+};
+
+/**
+ * Decide whether to throttle on-device inference for the current thermal /
+ * power state. Pure and synchronous so the streaming path can call it per token
+ * (the `ProcessInfo.thermalState` throttle hook the iOS streaming bridge still
+ * lists as a TODO) and the workbench can assert the policy without a device.
+ *
+ *   - `serious` / `critical` thermal → stop speculative decoding (matches the
+ *     existing one-shot MTP gate in `probeCapabilities`).
+ *   - `critical` thermal → additionally shed load.
+ *   - low-power mode → stop speculative decoding (honour the user's power intent).
+ *   - `unknown` thermal with no low-power signal → do not throttle (don't
+ *     penalise a device that simply lacks a thermal API).
+ */
+export function thermalThrottleDecision(input: {
+	thermalState: ThermalState | "unknown";
+	lowPowerMode?: boolean | null;
+}): ThermalThrottleDecision {
+	const lowPower = input.lowPowerMode === true;
+	if (input.thermalState === "unknown") {
+		return {
+			throttleSpeculativeDecode: lowPower,
+			reduceLoad: false,
+			reason: lowPower
+				? "low-power mode (thermal state unknown)"
+				: "thermal state unknown — no throttle",
+		};
+	}
+	const severity = THROTTLE_SEVERITY[input.thermalState];
+	const thermalThrottles = severity >= THROTTLE_SEVERITY.serious;
+	const reduceLoad = severity >= THROTTLE_SEVERITY.critical;
+	const throttleSpeculativeDecode = thermalThrottles || lowPower;
+	let reason: string;
+	if (reduceLoad) reason = `thermal ${input.thermalState} — shed load`;
+	else if (thermalThrottles)
+		reason = `thermal ${input.thermalState} — throttle speculative decode`;
+	else if (lowPower) reason = "low-power mode — throttle speculative decode";
+	else reason = `thermal ${input.thermalState} — nominal, no throttle`;
+	return { throttleSpeculativeDecode, reduceLoad, reason };
+}

package/src/services/inference-telemetry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lightweight structured-metrics sink for local-inference telemetry.
+ *
+ * This module is intentionally small: it is a logger-backed histogram with a
+ * stable, call-site-friendly `record(name, value, tags?)` API so individual
+ * backends (FFI runtime, voice scheduler, …) can emit point-in-time
+ * observations without importing a heavy metrics framework.
+ *
+ * Design constraints
+ * ------------------
+ * - No external dependencies beyond `@elizaos/core` logger (already a dep).
+ * - `record()` is synchronous and must never throw into the call site.
+ * - Each named metric keeps a bounded ring of recent samples (default 256) for
+ *   in-process p50/p95 queries via `summary(name)`. This mirrors the
+ *   `BoundedHistogram` pattern already used by `latency-trace.ts`.
+ * - The module exports a process-wide singleton (`inferenceTelemetry`) that
+ *   all backends share, plus the class for test injection.
+ *
+ * Metric names used today
+ * -----------------------
+ *   inference.ttfa_ms        — time from fetch() to first HTTP chunk (L5)
+ *   inference.first_token_ms — time from fetch() to first decoded token (L5)
+ *   tts.chunk_size_ms        — duration of one PCM chunk in ms (T2)
+ *   tts.chunk_size_bytes     — byte size of one PCM chunk (T2)
+ */
+interface HistogramSummary {
+    count: number;
+    p50: number | null;
+    p95: number | null;
+    mean: number | null;
+}
+export type TelemetryTags = Record<string, string | number | boolean>;
+export declare class InferenceTelemetry {
+    private readonly rings;
+    private readonly capacity;
+    constructor(capacity?: number);
+    /**
+     * Record a scalar observation. Never throws — telemetry must be
+     * instrumentation, never a fault path.
+     *
+     * @param name  Dot-separated metric name, e.g. `"inference.ttfa_ms"`.
+     * @param value Numeric value (non-finite values are silently dropped).
+     * @param tags  Optional key/value labels emitted in the log line.
+     */
+    record(name: string, value: number, tags?: TelemetryTags): void;
+    /**
+     * Summary statistics for a named metric over the retained ring of samples.
+     * Returns `{ count: 0, ... }` when the metric has never been recorded.
+     */
+    summary(name: string): HistogramSummary;
+    /** Names of all metrics that have received at least one sample. */
+    metricNames(): string[];
+    /** Reset all retained samples. Useful in tests. */
+    reset(): void;
+}
+/** Process-wide singleton used by FFI runtime and voice scheduler. */
+export declare const inferenceTelemetry: InferenceTelemetry;
+export {};
+//# sourceMappingURL=inference-telemetry.d.ts.map

package/src/services/inference-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-telemetry.d.ts","sourceRoot":"","sources":["inference-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,UAAU,gBAAgB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAwCD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEtE,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,SAAM;IAI1B;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI;IAoB/D;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB;IAWvC,mEAAmE;IACnE,WAAW,IAAI,MAAM,EAAE;IAIvB,mDAAmD;IACnD,KAAK,IAAI,IAAI;CAGb;AAED,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,oBAA2B,CAAC"}

package/src/services/inference-telemetry.ts

@@ -0,0 +1,143 @@
+/**
+ * Lightweight structured-metrics sink for local-inference telemetry.
+ *
+ * This module is intentionally small: it is a logger-backed histogram with a
+ * stable, call-site-friendly `record(name, value, tags?)` API so individual
+ * backends (FFI runtime, voice scheduler, …) can emit point-in-time
+ * observations without importing a heavy metrics framework.
+ *
+ * Design constraints
+ * ------------------
+ * - No external dependencies beyond `@elizaos/core` logger (already a dep).
+ * - `record()` is synchronous and must never throw into the call site.
+ * - Each named metric keeps a bounded ring of recent samples (default 256) for
+ *   in-process p50/p95 queries via `summary(name)`. This mirrors the
+ *   `BoundedHistogram` pattern already used by `latency-trace.ts`.
+ * - The module exports a process-wide singleton (`inferenceTelemetry`) that
+ *   all backends share, plus the class for test injection.
+ *
+ * Metric names used today
+ * -----------------------
+ *   inference.ttfa_ms        — time from fetch() to first HTTP chunk (L5)
+ *   inference.first_token_ms — time from fetch() to first decoded token (L5)
+ *   tts.chunk_size_ms        — duration of one PCM chunk in ms (T2)
+ *   tts.chunk_size_bytes     — byte size of one PCM chunk (T2)
+ */
+
+import { logger } from "@elizaos/core";
+
+// ---------------------------------------------------------------------------
+// Bounded histogram (copied structure from latency-trace.ts — same project)
+// ---------------------------------------------------------------------------
+
+interface HistogramSummary {
+	count: number;
+	p50: number | null;
+	p95: number | null;
+	mean: number | null;
+}
+
+class BoundedRing {
+	private readonly buf: number[];
+	private head = 0;
+	private filled = 0;
+
+	constructor(private readonly cap: number) {
+		this.buf = new Array<number>(cap).fill(0);
+	}
+
+	push(v: number): void {
+		if (!Number.isFinite(v)) return;
+		this.buf[this.head] = v;
+		this.head = (this.head + 1) % this.cap;
+		if (this.filled < this.cap) this.filled += 1;
+	}
+
+	summary(): HistogramSummary {
+		if (this.filled === 0)
+			return { count: 0, p50: null, p95: null, mean: null };
+		const slice = this.buf.slice(0, this.filled).sort((a, b) => a - b);
+		const pct = (q: number): number => {
+			const rank = Math.ceil((q / 100) * slice.length);
+			return slice[Math.min(slice.length - 1, Math.max(0, rank - 1))] as number;
+		};
+		const sum = slice.reduce((a, b) => a + b, 0);
+		return {
+			count: this.filled,
+			p50: pct(50),
+			p95: pct(95),
+			mean: sum / this.filled,
+		};
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type TelemetryTags = Record<string, string | number | boolean>;
+
+export class InferenceTelemetry {
+	private readonly rings = new Map<string, BoundedRing>();
+	private readonly capacity: number;
+
+	constructor(capacity = 256) {
+		this.capacity = capacity;
+	}
+
+	/**
+	 * Record a scalar observation. Never throws — telemetry must be
+	 * instrumentation, never a fault path.
+	 *
+	 * @param name  Dot-separated metric name, e.g. `"inference.ttfa_ms"`.
+	 * @param value Numeric value (non-finite values are silently dropped).
+	 * @param tags  Optional key/value labels emitted in the log line.
+	 */
+	record(name: string, value: number, tags?: TelemetryTags): void {
+		try {
+			let ring = this.rings.get(name);
+			if (!ring) {
+				ring = new BoundedRing(this.capacity);
+				this.rings.set(name, ring);
+			}
+			ring.push(value);
+			const tagStr = tags
+				? " " +
+					Object.entries(tags)
+						.map(([k, v]) => `${k}=${v}`)
+						.join(" ")
+				: "";
+			logger.debug(`[InferenceTelemetry] ${name}=${value}${tagStr}`);
+		} catch {
+			// Swallow — telemetry must never surface as a runtime error.
+		}
+	}
+
+	/**
+	 * Summary statistics for a named metric over the retained ring of samples.
+	 * Returns `{ count: 0, ... }` when the metric has never been recorded.
+	 */
+	summary(name: string): HistogramSummary {
+		return (
+			this.rings.get(name)?.summary() ?? {
+				count: 0,
+				p50: null,
+				p95: null,
+				mean: null,
+			}
+		);
+	}
+
+	/** Names of all metrics that have received at least one sample. */
+	metricNames(): string[] {
+		return [...this.rings.keys()];
+	}
+
+	/** Reset all retained samples. Useful in tests. */
+	reset(): void {
+		this.rings.clear();
+	}
+}
+
+/** Process-wide singleton used by FFI runtime and voice scheduler. */
+export const inferenceTelemetry = new InferenceTelemetry();

package/src/services/ios-llama-streaming.ts

@@ -0,0 +1,248 @@
+/**
+ * iOS streaming-LLM adapter.
+ *
+ * Mirror of the AOSP plugin's `aosp-llama-streaming.ts` for the iOS
+ * platform.  Bridges the JS-side streaming surface (the same shape the
+ * `FfiStreamingRunner` expects) over the `LlamaCpp.xcframework` Swift
+ * bridge that ships with the iOS shell.
+ *
+ * Status (2026-05-12): the XCFramework currently ships without streaming-LLM
+ * support. The Swift implementation against
+ * `libelizainference.dylib` (built by `build-llama-cpp-mtp.mjs` with
+ * the `darwin-arm64-metal-fused` target) is the gating item; until then
+ * `loadIosStreamingLlmBinding` returns `null` and the runtime falls
+ * back to the cloud route.
+ *
+ * Why XCFramework + Swift bridge rather than `bun:ffi` directly:
+ *   - bun:ffi runs only inside the Bun runtime.  On iOS, Eliza ships the
+ *     ElizaBunEngine.xcframework which embeds a Bun runtime — but the
+ *     llama symbols cannot be resolved at `bun:ffi.dlopen` time on a
+ *     codesigned device build (the dynamic linker forbids loading
+ *     arbitrary `.dylib` from the app bundle on a real device).
+ *   - The Swift bridge wraps the symbols at compile time inside the
+ *     XCFramework so the codesignature covers them.  Capacitor's
+ *     `llama-cpp-capacitor` plugin already uses this pattern for the
+ *     non-streaming surface.
+ *
+ * The Swift glue gating this binding needs to:
+ *   1. Re-export the streaming-LLM symbols from `ffi-streaming-llm.h`
+ *      under the Swift module name `LlamaCpp.Streaming.*`.
+ *   2. Expose an Objective-C-bridgeable wrapper class
+ *      (`LlamaStreamingSession`) so Capacitor's plugin can register
+ *      methods on it.
+ *   3. Wire `ProcessInfo.thermalState` into a thermal-throttle hook so
+ *      iOS can bail out of speculative decoding under sustained heat.
+ *
+ * Until that lands, this file:
+ *   - declares the JS contract,
+ *   - probes for `(window as any).LlamaStreaming` (the Capacitor plugin
+ *     entry point Swift will expose),
+ *   - logs + returns null when the bridge isn't there.
+ */
+
+import { logger } from "@elizaos/core";
+
+/* -------------------------------------------------------------------- */
+/* Public types — identical shape to the AOSP binding so the runner     */
+/* doesn't know or care which platform it's on.                         */
+/* -------------------------------------------------------------------- */
+
+export type IosLlmStreamHandle = bigint;
+export type IosInferenceContextHandle = bigint;
+
+export interface IosLlmStreamConfig {
+	maxTokens: number;
+	temperature: number;
+	topP: number;
+	topK: number;
+	repeatPenalty: number;
+	slotId: number;
+	promptCacheKey: string | null;
+	draftMin: number;
+	draftMax: number;
+	mtpDrafterPath: string | null;
+	disableThinking: boolean;
+}
+
+export interface IosLlmStreamStep {
+	tokens: number[];
+	text: string;
+	done: boolean;
+	drafterDrafted: number;
+	drafterAccepted: number;
+}
+
+export interface IosStreamingLlmBinding {
+	llmStreamSupported(): boolean;
+	llmStreamOpen(args: {
+		ctx: IosInferenceContextHandle;
+		config: IosLlmStreamConfig;
+	}): IosLlmStreamHandle;
+	llmStreamPrefill(args: {
+		stream: IosLlmStreamHandle;
+		tokens: Int32Array;
+	}): void;
+	llmStreamNext(args: {
+		stream: IosLlmStreamHandle;
+		maxTokensPerStep?: number;
+		maxTextBytes?: number;
+	}): IosLlmStreamStep;
+	llmStreamCancel(stream: IosLlmStreamHandle): void;
+	llmStreamSaveSlot(args: {
+		stream: IosLlmStreamHandle;
+		filename: string;
+	}): void;
+	llmStreamRestoreSlot(args: {
+		stream: IosLlmStreamHandle;
+		filename: string;
+	}): void;
+	llmStreamClose(stream: IosLlmStreamHandle): void;
+}
+
+/* -------------------------------------------------------------------- */
+/* Capacitor bridge contract                                            */
+/*                                                                      */
+/* Shape the Swift side must expose.  Capacitor exposes plugin methods  */
+/* via `window.Capacitor.Plugins.LlamaStreaming` once the bridge is     */
+/* registered.  Each method is a Promise on the JS side (Capacitor      */
+/* serialises across the JS↔native bridge), so the synchronous          */
+/* `IosStreamingLlmBinding` shape is built by `loadIosStreamingLlmBinding`*/
+/* over a small adapter — but the underlying bridge is async.           */
+/* -------------------------------------------------------------------- */
+
+interface CapacitorLlamaStreamingPlugin {
+	isAvailable(): Promise<{ available: boolean }>;
+	open(args: {
+		ctxHandle: string; // bigint serialised as string over the bridge
+		config: IosLlmStreamConfig;
+	}): Promise<{ streamHandle: string }>;
+	prefill(args: { streamHandle: string; tokens: number[] }): Promise<void>;
+	/**
+	 * Iteration is event-based on the native side — Capacitor plugin
+	 * `addListener("llmStreamStep", cb)` fires for each step.  The JS
+	 * binding shape we want is synchronous-ish for symmetry with bun:ffi;
+	 * the adapter in `buildIosBinding`
+	 * will turn the listener stream into a `next()`-like queue.
+	 */
+	cancel(args: { streamHandle: string }): Promise<void>;
+	saveSlot(args: { streamHandle: string; filename: string }): Promise<void>;
+	restoreSlot(args: { streamHandle: string; filename: string }): Promise<void>;
+	close(args: { streamHandle: string }): Promise<void>;
+}
+
+interface CapacitorWindow {
+	Capacitor?: {
+		Plugins?: {
+			LlamaStreaming?: CapacitorLlamaStreamingPlugin;
+		};
+		isNativePlatform?(): boolean;
+		getPlatform?(): string;
+	};
+}
+
+function tryGetCapacitorPlugin(): CapacitorLlamaStreamingPlugin | null {
+	const w = globalThis as unknown as CapacitorWindow;
+	const plugin = w.Capacitor?.Plugins?.LlamaStreaming;
+	if (!plugin) return null;
+	if (
+		typeof plugin.open !== "function" ||
+		typeof plugin.prefill !== "function" ||
+		typeof plugin.cancel !== "function" ||
+		typeof plugin.close !== "function"
+	) {
+		return null;
+	}
+	return plugin;
+}
+
+/* -------------------------------------------------------------------- */
+/* Loader                                                               */
+/* -------------------------------------------------------------------- */
+
+/**
+ * Try to load the iOS streaming-LLM binding.  Returns null when:
+ *   - we are not on iOS,
+ *   - the Capacitor `LlamaStreaming` plugin isn't registered,
+ *   - the bridge reports `isAvailable() === false` (e.g. the XCFramework
+ *     was built without streaming-LLM support).
+ *
+ * Returning null is NOT a failure — the runtime then falls back to the
+ * cloud route.  Throws only when the bridge is present but
+ * mis-configured (probe-and-catch is reserved for the boot path).
+ */
+export async function loadIosStreamingLlmBinding(): Promise<IosStreamingLlmBinding | null> {
+	const plugin = tryGetCapacitorPlugin();
+	if (!plugin) {
+		logger.info(
+			"[ios-llama-streaming] No Capacitor LlamaStreaming plugin registered. " +
+				"iOS streaming-LLM unavailable.",
+		);
+		return null;
+	}
+	const probe = await plugin.isAvailable().catch((err: unknown) => {
+		logger.warn(
+			`[ios-llama-streaming] isAvailable probe threw: ${formatError(err)}`,
+		);
+		return { available: false };
+	});
+	if (!probe.available) {
+		logger.info(
+			"[ios-llama-streaming] LlamaCpp.xcframework reports streaming-LLM " +
+				"unsupported (shim build).  See docs/eliza-1-ios-streaming-status.md.",
+		);
+		return null;
+	}
+	return buildIosBinding(plugin);
+}
+
+/**
+ * Wrap the async Capacitor plugin in the synchronous-ish JS contract
+ * `FfiStreamingRunner` expects.  Internally this means buffering
+ * `llmStreamStep` events from the Capacitor listener bus into a JS
+ * queue keyed by stream handle, then having `llmStreamNext` block on a
+ * `Promise<step>`.
+ *
+ * Unavailable adapter body. Until the Swift bridge reports streaming support,
+ * this code path is unreachable because the loader returns null first. The
+ * shape is here so app-core wiring compiles against the platform contract.
+ */
+function buildIosBinding(
+	_plugin: CapacitorLlamaStreamingPlugin,
+): IosStreamingLlmBinding {
+	throw new Error(
+		"[ios-llama-streaming] buildIosBinding is unavailable. " +
+			"The Swift bridge (LlamaStreaming Capacitor plugin) is not wired. " +
+			"See docs/eliza-1-ios-streaming-status.md for the rollout plan.",
+	);
+}
+
+function formatError(err: unknown): string {
+	if (err instanceof Error) return err.message;
+	try {
+		return JSON.stringify(err);
+	} catch {
+		return String(err);
+	}
+}
+
+/* -------------------------------------------------------------------- */
+/* Capability probe                                                     */
+/* -------------------------------------------------------------------- */
+
+export interface IosInferenceCapabilities {
+	/** True only when the iOS Swift bridge is present AND reports streaming-LLM. */
+	streamingLlm: boolean;
+	/** Always false on iOS until the drafter weights ship in the bundle. */
+	mtpSupported: boolean;
+	/** Whether the XCFramework reports omnivoice streaming. */
+	omnivoiceStreaming: boolean;
+	/** Phone-tier iOS devices rarely have headroom for mmproj. */
+	mmprojSupported: boolean;
+	/**
+	 * `ProcessInfo.thermalState` snapshot at probe time.  Surfaced so the
+	 * runtime can refuse to start speculative decoding when the device is
+	 * already in `serious` / `critical`.  Always `nominal` on the
+	 * web/sim fallback path.
+	 */
+	thermalState: "nominal" | "fair" | "serious" | "critical";
+}