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

package/src/services/imagegen/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Local image-generation (diffusion) types — WS3 deliverable.
+ *
+ * Two layers live here, mirroring the WS2 vision-describe split:
+ *
+ *   1. The **request/result** contract every WS3 backend implements
+ *      (`ImageGenRequest`, `ImageGenResult`). Callers pass a text prompt
+ *      and optional knobs; backends return PNG (or JPEG) bytes + metadata.
+ *
+ *   2. The **backend** interface (`ImageGenBackend`) that the
+ *      `MemoryArbiter` (WS1) registers as a capability handler. One
+ *      backend per per-platform diffusion runtime:
+ *
+ *        - `sd-cpp` — stable-diffusion.cpp child-process binary
+ *          (Linux + Windows + Android JNI).
+ *        - `mflux`  — MLX `mflux` Python venv (macOS Apple Silicon).
+ *        - `coreml` — Capacitor bridge to Swift `apple/ml-stable-diffusion`
+ *          (iOS only).
+ *        - `tensorrt` — packaged `imagegen.exe` / `trtexec` wrapper
+ *          (Windows NVIDIA).
+ *        - `aosp`   — bun:ffi to `eliza_llama_imagegen_*` symbols in
+ *          libeliza-llama-shim (Android JNI; unavailable until shim ships).
+ *        - `fake`   — deterministic in-process backend used by tests.
+ *
+ * All backends implement the same `load → generate → dispose` shape so the
+ * arbiter can swap between them without caring how the diffusion runtime
+ * is wired.
+ *
+ * Cache contract:
+ *
+ *   Image-gen requests do NOT go through `hashVisionInput` (that's the
+ *   WS2 projector-token cache, which lives on image *inputs*). The
+ *   request-side keying space is prompt + seed + steps + scheduler + …;
+ *   if a cache lands here later it gets its own namespace (`hashImageGenRequest`)
+ *   to avoid collisions with the WS2 vision-embedding cache. For now the
+ *   capability has no result cache — diffusion is intrinsically expensive
+ *   and most callers want a fresh sample, not a cached one.
+ */
+
+/** Output container the backend writes. PNG is default; JPEG is opt-in. */
+export type ImageGenMimeType = "image/png" | "image/jpeg";
+
+/**
+ * Caller request to `generate`. All fields except `prompt` are optional —
+ * backends apply per-runtime defaults for missing knobs.
+ *
+ * Knob semantics (consistent across backends):
+ *
+ *   - `width` / `height`: pixel resolution. Default 512×512 (SD 1.5 family) /
+ *     1024×1024 (SDXL / FLUX / Z-Image). Backends round to the nearest
+ *     multiple of 8 (SD) or 16 (SDXL) when needed.
+ *   - `steps`: denoising step count. 4 for FLUX schnell / Z-Image-Turbo
+ *     (single-pass Turbo schedulers); 20 for SD 1.5 Euler-A; 25 for SDXL.
+ *   - `guidanceScale`: classifier-free guidance. Ignored by FLUX schnell
+ *     (CFG-free). 7.5 default for SD 1.5; 4.0 default for SDXL.
+ *   - `seed`: PRNG seed. -1 / omitted → random; the backend returns the
+ *     actual seed used in `ImageGenResult.seed` so the caller can replay.
+ *   - `scheduler`: sampler name (`"euler-a"`, `"dpm++-2m"`, `"ddim"`,
+ *     `"euler"`). Backends accept the strings their underlying runtime
+ *     supports; unknown values raise `ImageGenBackendUnavailableError`.
+ */
+export interface ImageGenRequest {
+	prompt: string;
+	negativePrompt?: string;
+	width?: number;
+	height?: number;
+	steps?: number;
+	guidanceScale?: number;
+	seed?: number;
+	scheduler?: string;
+	signal?: AbortSignal;
+	/**
+	 * Optional per-step progress callback. Called once per denoising step
+	 * with `{ step, total }`. Backends that can't surface step-level
+	 * progress (Core ML batch fused path, TensorRT static engine) MAY
+	 * call this once with `step === total` at completion instead of
+	 * per-step. Never required.
+	 */
+	onProgressChunk?: (progress: { step: number; total: number }) => void;
+}
+
+/**
+ * Backend response. `image` is the raw bytes (PNG by default); `mime`
+ * identifies the container. The metadata block carries enough state for
+ * the caller to attach to a chat turn, log to trajectories, or feed the
+ * result back into a vision-describe for the same agent.
+ */
+export interface ImageGenResult {
+	image: Uint8Array;
+	mime: ImageGenMimeType;
+	/**
+	 * The actual seed the diffusion run used. Always populated — the
+	 * backend MUST resolve a random seed before sampling and report it
+	 * here. This is what makes a generation reproducible.
+	 */
+	seed: number;
+	metadata: {
+		/** The model id (catalog key) the run used (`"imagegen-sd-1_5-q5_0"`, etc.). */
+		model: string;
+		/** Echo of the prompt that was sampled. */
+		prompt: string;
+		/** Echo of the step count actually used (post-default-resolve). */
+		steps: number;
+		/** Echo of CFG actually applied. 0 for CFG-free models (FLUX schnell). */
+		guidanceScale: number;
+		/** End-to-end wall-clock time inside the backend. */
+		inferenceTimeMs: number;
+	};
+}
+
+/**
+ * Per-load arguments for an image-gen backend. The arbiter's
+ * `load(modelKey)` only carries an opaque key; the binding resolves that
+ * key to real model+vae+clip+t5 paths through this struct, which
+ * `createImageGenCapabilityRegistration` populates from the catalog +
+ * `ELIZA_1_BUNDLE_EXTRAS.json`.
+ *
+ * Some diffusion families are single-file GGUFs once quantized, such as
+ * SD 1.5 Q5_0. Others stay split: stable-diffusion.cpp runs Z-Image
+ * with `--diffusion-model` plus separate Qwen LLM text encoder and VAE
+ * files. The optional paths below carry those companion assets.
+ */
+export interface ImageGenLoadArgs {
+	/** Absolute path to the primary diffusion weights (GGUF / mlpackage / engine). */
+	modelPath: string;
+	/**
+	 * Treat `modelPath` as a stable-diffusion.cpp `--diffusion-model` rather
+	 * than a monolithic `--model`. Required for Z-Image/Flux-style split
+	 * diffusion bundles.
+	 */
+	splitDiffusionModel?: boolean;
+	/** Optional split VAE path. */
+	vae?: string;
+	/** Optional split CLIP-L / CLIP-G path. */
+	clip?: string;
+	/** Optional split T5 / Gemma text encoder path. */
+	t5?: string;
+	/** Optional split LLM text encoder path, e.g. Qwen3 for Z-Image. */
+	llm?: string;
+	/**
+	 * Backend-specific acceleration hint. Accepts:
+	 *   - `"auto"` (default) — let the binding decide.
+	 *   - `"cpu"` — force CPU.
+	 *   - `"cuda"` / `"vulkan"` / `"metal"` / `"coreml"` / `"qnn"` /
+	 *     `"tensorrt"` — request a specific accelerator. Unsupported
+	 *     requests fall back to `auto`.
+	 */
+	accelerator?:
+		| "auto"
+		| "cpu"
+		| "cuda"
+		| "vulkan"
+		| "metal"
+		| "coreml"
+		| "qnn"
+		| "tensorrt";
+	/** Cancel a slow load (model file read + weight upload). */
+	signal?: AbortSignal;
+}
+
+/**
+ * The contract every WS3 backend implements. The shape is intentionally
+ * narrow: the arbiter only ever calls `generate`. `dispose` is wrapped
+ * by the arbiter's `unload` so the backend can free GPU/VRAM and drop
+ * file descriptors / kill subprocesses on eviction.
+ */
+export interface ImageGenBackend {
+	/** Stable identifier — matches the backend module name. */
+	readonly id: "sd-cpp" | "mflux" | "coreml" | "tensorrt" | "aosp" | "fake";
+	/**
+	 * Best-effort capability check. Implementations return `false` for
+	 * requests whose `width`/`height`/`scheduler` aren't supported by
+	 * the loaded weights, so the arbiter can fall through to the next
+	 * registered backend (selector order). Default backends accept
+	 * anything reasonable; `supports` mostly matters for `coreml`
+	 * (fixed resolution per `.mlpackage`) and `tensorrt` (fixed engine
+	 * shape).
+	 */
+	supports(request: ImageGenRequest): boolean;
+	generate(request: ImageGenRequest): Promise<ImageGenResult>;
+	/** Release the loaded weights / subprocess. Idempotent. */
+	dispose(): Promise<void>;
+}
+
+/**
+ * Capability handler loader. The arbiter calls it with a model key
+ * (e.g. `"imagegen-sd-1_5-q5_0"`); the implementation resolves to a
+ * real `ImageGenLoadArgs` from `ELIZA_1_BUNDLE_EXTRAS.json` + the
+ * installed bundle and returns a live backend.
+ */
+export type ImageGenBackendLoader = (
+	modelKey: string,
+) => Promise<ImageGenBackend>;

package/src/services/index.d.ts

@@ -0,0 +1,29 @@
+export type { LocalInferenceLoader } from "./active-model";
+export { assertVoiceBundleFitsHost, VoiceBundleDoesNotFitError, } from "./active-model";
+export { type BackendDecision, BackendDispatcher, type BackendOverride, type BackendPlan, decideBackend, type GenerateArgs as BackendGenerateArgs, type GenerateResult, type LocalInferenceBackend, readBackendOverride, resolveCatalogForPlan, } from "./backend";
+export { ELIZA_1_PLACEHOLDER_IDS, FIRST_RUN_DEFAULT_MODEL_ID, findCatalogModel, MODEL_CATALOG, } from "./catalog";
+export { type CloudCandidate, type CloudFallbackOptions, classifyLocalError, type FallbackReason, findCloudCandidate, type LocalGenerateOutcome, makeCloudFallbackHandler, } from "./cloud-fallback";
+export { buildDeviceResourceMetricsDevPayload, type DeviceBridgeStatus, type DeviceGenerationMetrics, type DeviceResourceMetricsDevPayload, deviceBridge, } from "./device-bridge";
+export { type BatterySummary, DeviceResourceMetrics, type DeviceResourceSummary, type DeviceThermalState, type GenerationObservation, type LowPowerSummary, type ResourceSample, type RssSummary, type ThermalSummary, type ThermalTransition, } from "./device-resource-metrics";
+export { classifyDeviceTier, DEVICE_TIER_ORDER, DEVICE_TIER_THRESHOLDS, type DeviceTier, type DeviceTierAssessment, effectiveModelMemoryGb, type RecommendedMode, TIER_WARNING_COPY, totalRamMb, } from "./device-tier";
+export { LocalInferenceEngine, localInferenceEngine, resolveIdleUnloadMs, resolveMaxConcurrentSpeculativeResponses, } from "./engine";
+export { type HandlerRegistration, handlerRegistry, type PublicRegistration, toPublicRegistration, } from "./handler-registry";
+export { assessFit, probeHardware } from "./hardware";
+export { createImageDescriptionRuntime, type ImageDescriptionRuntime, type ImageDescriptionRuntimeOptions, } from "./image-description-runtime";
+export { type CapabilityProbes, defaultsForNoBinding, type InferenceCapabilities, probeCapabilities, type ResourceSnapshot, type ThermalState, type ThermalThrottleDecision, thermalThrottleDecision, } from "./inference-capabilities";
+export { InferenceTelemetry, inferenceTelemetry, type TelemetryTags, } from "./inference-telemetry";
+export { estimateQuantizedKvBytesPerToken, KV_SPILL_MIN_CONTEXT, type KvGeometry, type KvRestoreClass, type KvSpillPlan, KvSpillUnsupportedError, planKvSpill, } from "./kv-spill";
+export { buildVoiceLatencyDevPayload, EndToEndLatencyTracer, endVoiceLatencyTurn, type HistogramSummary, LATENCY_DERIVED_KEYS, type LatencyCheckpoint, type LatencyDerived, type LatencyDerivedKey, type LatencyTrace, markVoiceLatency, type TracerOptions, VOICE_CHECKPOINTS, type VoiceCheckpoint, type VoiceLatencyDevPayload, voiceLatencyTracer, } from "./latency-trace";
+export * from "./manifest/index";
+export { type ArbiterCapability, type ArbiterEvent, type ArbiterEventListener, type ArbiterHandle, type CapabilityRegistration, getMemoryArbiter, MemoryArbiter, type MemoryArbiterOptions, setMemoryArbiter, tryGetMemoryArbiter, } from "./memory-arbiter";
+export { type CapacitorPressureSource, capacitorPressureSource, compositePressureSource, type MemoryPressureEvent, type MemoryPressureLevel, type MemoryPressureListener, type MemoryPressureSource, nodeOsPressureSource, } from "./memory-pressure";
+export { type MtpDoctorCheck, type MtpDoctorCheckStatus, type MtpDoctorReport, runMtpDoctor, } from "./mtp-doctor";
+export { buildPlanActionsSkeleton, buildPlannerGuidedDecode, type PlannerAction, type PlannerGuidedDecode, planActionParameterSchema, } from "./planner-skeleton";
+export { buildTextGenerationReadiness } from "./readiness";
+export { assessCatalogModelFit, type BundleDefaultEligibility, canBundleBeDefaultOnDevice, catalogDownloadSizeBytes, catalogDownloadSizeGb, chooseSmallerFallbackModel, classifyRecommendationPlatform, deviceCapsFromProbe, type RecommendationPlatformClass, type RecommendedModelSelection, recommendForFirstRun, selectBestQuantizationVariant, selectRecommendedModelForSlot, selectRecommendedModels, } from "./recommendation";
+export { type InferenceRuntimeMode, type InferenceRuntimeModeInput, inferencePlatformClass, inferenceRuntimeMode, isCapacitorNativeRuntime, readRuntimeModeEnvOverride, type SupportedHostPlatform, } from "./runtime-target";
+export { LocalInferenceService, localInferenceService } from "./service";
+export type { ActiveModelState, CatalogModel, DownloadEvent, DownloadJob, DownloadState, HardwareFitLevel, HardwareProbe, InstalledModel, LocalInferenceDownloadStatus, LocalInferenceReadiness, LocalInferenceSlotReadiness, LocalRuntimeAcceleration, LocalRuntimeBackend, LocalRuntimeKernel, LocalRuntimeOptimizations, ModelBucket, ModelCategory, ModelHubSnapshot, TextGenerationSlot, } from "./types";
+export { VisionEmbeddingCache, type VisionEmbeddingCacheConfig, type VisionEmbeddingEntry, } from "./vision-embedding-cache";
+export * from "./voice/index";
+//# sourceMappingURL=index.d.ts.map

package/src/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EACN,yBAAyB,EACzB,0BAA0B,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,KAAK,eAAe,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,aAAa,EACb,KAAK,YAAY,IAAI,mBAAmB,EACxC,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,wBAAwB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,oCAAoC,EACpC,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,+BAA+B,EACpC,YAAY,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,KAAK,eAAe,EACpB,iBAAiB,EACjB,UAAU,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wCAAwC,GACxC,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,KAAK,mBAAmB,EACxB,eAAe,EACf,KAAK,kBAAkB,EACvB,oBAAoB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EACN,6BAA6B,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,GACnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,uBAAuB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,gCAAgC,EAChC,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,uBAAuB,EACvB,WAAW,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,gBAAgB,EAChB,KAAK,aAAa,EAClB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,kBAAkB,GAClB,MAAM,iBAAiB,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,aAAa,EACb,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,KAAK,uBAAuB,EAC5B,uBAAuB,EACvB,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,YAAY,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,yBAAyB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACN,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,mBAAmB,EACnB,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,6BAA6B,EAC7B,6BAA6B,EAC7B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,qBAAqB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACzE,YAAY,EACX,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EACN,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,GACzB,MAAM,0BAA0B,CAAC;AAClC,cAAc,eAAe,CAAC"}

package/src/services/index.ts

@@ -0,0 +1,211 @@
+export type { LocalInferenceLoader } from "./active-model";
+export {
+	assertVoiceBundleFitsHost,
+	VoiceBundleDoesNotFitError,
+} from "./active-model";
+export {
+	type BackendDecision,
+	BackendDispatcher,
+	type BackendOverride,
+	type BackendPlan,
+	decideBackend,
+	type GenerateArgs as BackendGenerateArgs,
+	type GenerateResult,
+	type LocalInferenceBackend,
+	readBackendOverride,
+	resolveCatalogForPlan,
+} from "./backend";
+export {
+	ELIZA_1_PLACEHOLDER_IDS,
+	FIRST_RUN_DEFAULT_MODEL_ID,
+	findCatalogModel,
+	MODEL_CATALOG,
+} from "./catalog";
+export {
+	type CloudCandidate,
+	type CloudFallbackOptions,
+	classifyLocalError,
+	type FallbackReason,
+	findCloudCandidate,
+	type LocalGenerateOutcome,
+	makeCloudFallbackHandler,
+} from "./cloud-fallback";
+export {
+	buildDeviceResourceMetricsDevPayload,
+	type DeviceBridgeStatus,
+	type DeviceGenerationMetrics,
+	type DeviceResourceMetricsDevPayload,
+	deviceBridge,
+} from "./device-bridge";
+export {
+	type BatterySummary,
+	DeviceResourceMetrics,
+	type DeviceResourceSummary,
+	type DeviceThermalState,
+	type GenerationObservation,
+	type LowPowerSummary,
+	type ResourceSample,
+	type RssSummary,
+	type ThermalSummary,
+	type ThermalTransition,
+} from "./device-resource-metrics";
+export {
+	classifyDeviceTier,
+	DEVICE_TIER_ORDER,
+	DEVICE_TIER_THRESHOLDS,
+	type DeviceTier,
+	type DeviceTierAssessment,
+	effectiveModelMemoryGb,
+	type RecommendedMode,
+	TIER_WARNING_COPY,
+	totalRamMb,
+} from "./device-tier";
+export {
+	LocalInferenceEngine,
+	localInferenceEngine,
+	resolveIdleUnloadMs,
+	resolveMaxConcurrentSpeculativeResponses,
+} from "./engine";
+export {
+	type HandlerRegistration,
+	handlerRegistry,
+	type PublicRegistration,
+	toPublicRegistration,
+} from "./handler-registry";
+export { assessFit, probeHardware } from "./hardware";
+export {
+	createImageDescriptionRuntime,
+	type ImageDescriptionRuntime,
+	type ImageDescriptionRuntimeOptions,
+} from "./image-description-runtime";
+export {
+	type CapabilityProbes,
+	defaultsForNoBinding,
+	type InferenceCapabilities,
+	probeCapabilities,
+	type ResourceSnapshot,
+	type ThermalState,
+	type ThermalThrottleDecision,
+	thermalThrottleDecision,
+} from "./inference-capabilities";
+export {
+	InferenceTelemetry,
+	inferenceTelemetry,
+	type TelemetryTags,
+} from "./inference-telemetry";
+export {
+	estimateQuantizedKvBytesPerToken,
+	KV_SPILL_MIN_CONTEXT,
+	type KvGeometry,
+	type KvRestoreClass,
+	type KvSpillPlan,
+	KvSpillUnsupportedError,
+	planKvSpill,
+} from "./kv-spill";
+export {
+	buildVoiceLatencyDevPayload,
+	EndToEndLatencyTracer,
+	endVoiceLatencyTurn,
+	type HistogramSummary,
+	LATENCY_DERIVED_KEYS,
+	type LatencyCheckpoint,
+	type LatencyDerived,
+	type LatencyDerivedKey,
+	type LatencyTrace,
+	markVoiceLatency,
+	type TracerOptions,
+	VOICE_CHECKPOINTS,
+	type VoiceCheckpoint,
+	type VoiceLatencyDevPayload,
+	voiceLatencyTracer,
+} from "./latency-trace";
+export * from "./manifest/index";
+export {
+	type ArbiterCapability,
+	type ArbiterEvent,
+	type ArbiterEventListener,
+	type ArbiterHandle,
+	type CapabilityRegistration,
+	getMemoryArbiter,
+	MemoryArbiter,
+	type MemoryArbiterOptions,
+	setMemoryArbiter,
+	tryGetMemoryArbiter,
+} from "./memory-arbiter";
+export {
+	type CapacitorPressureSource,
+	capacitorPressureSource,
+	compositePressureSource,
+	type MemoryPressureEvent,
+	type MemoryPressureLevel,
+	type MemoryPressureListener,
+	type MemoryPressureSource,
+	nodeOsPressureSource,
+} from "./memory-pressure";
+export {
+	type MtpDoctorCheck,
+	type MtpDoctorCheckStatus,
+	type MtpDoctorReport,
+	runMtpDoctor,
+} from "./mtp-doctor";
+export {
+	buildPlanActionsSkeleton,
+	buildPlannerGuidedDecode,
+	type PlannerAction,
+	type PlannerGuidedDecode,
+	planActionParameterSchema,
+} from "./planner-skeleton";
+export { buildTextGenerationReadiness } from "./readiness";
+export {
+	assessCatalogModelFit,
+	type BundleDefaultEligibility,
+	canBundleBeDefaultOnDevice,
+	catalogDownloadSizeBytes,
+	catalogDownloadSizeGb,
+	chooseSmallerFallbackModel,
+	classifyRecommendationPlatform,
+	deviceCapsFromProbe,
+	type RecommendationPlatformClass,
+	type RecommendedModelSelection,
+	recommendForFirstRun,
+	selectBestQuantizationVariant,
+	selectRecommendedModelForSlot,
+	selectRecommendedModels,
+} from "./recommendation";
+export {
+	type InferenceRuntimeMode,
+	type InferenceRuntimeModeInput,
+	inferencePlatformClass,
+	inferenceRuntimeMode,
+	isCapacitorNativeRuntime,
+	readRuntimeModeEnvOverride,
+	type SupportedHostPlatform,
+} from "./runtime-target";
+export { LocalInferenceService, localInferenceService } from "./service";
+export type {
+	ActiveModelState,
+	CatalogModel,
+	DownloadEvent,
+	DownloadJob,
+	DownloadState,
+	HardwareFitLevel,
+	HardwareProbe,
+	InstalledModel,
+	LocalInferenceDownloadStatus,
+	LocalInferenceReadiness,
+	LocalInferenceSlotReadiness,
+	LocalRuntimeAcceleration,
+	LocalRuntimeBackend,
+	LocalRuntimeKernel,
+	LocalRuntimeOptimizations,
+	ModelBucket,
+	ModelCategory,
+	ModelHubSnapshot,
+	TextGenerationSlot,
+} from "./types";
+export {
+	VisionEmbeddingCache,
+	type VisionEmbeddingCacheConfig,
+	type VisionEmbeddingEntry,
+} from "./vision-embedding-cache";
+export * from "./voice/index";

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

@@ -0,0 +1,132 @@
+/**
+ * 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 declare function probeCapabilities(probes: CapabilityProbes): InferenceCapabilities;
+/**
+ * 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 declare function defaultsForNoBinding(): InferenceCapabilities;
+/**
+ * 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;
+}
+/**
+ * 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 declare function thermalThrottleDecision(input: {
+    thermalState: ThermalState | "unknown";
+    lowPowerMode?: boolean | null;
+}): ThermalThrottleDecision;
+//# sourceMappingURL=inference-capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inference-capabilities.d.ts","sourceRoot":"","sources":["inference-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACrC,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;CACpD;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,kBAAkB,IAAI,OAAO,CAAC;IAC9B,yEAAyE;IACzE,kBAAkB,IAAI,OAAO,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,IAAI,OAAO,CAAC;IACvB,mEAAmE;IACnE,cAAc,IAAI,OAAO,CAAC;IAC1B,0FAA0F;IAC1F,YAAY,IAAI,YAAY,CAAC;IAC7B,oBAAoB;IACpB,QAAQ,IAAI,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,gBAAgB,GACtB,qBAAqB,CAqBvB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,qBAAqB,CAS5D;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAChC,6EAA6E;IAC7E,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;IACvC,yEAAyE;IACzE,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gDAAgD;IAChD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kDAAkD;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qCAAqC;IACrC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACvC;;;OAGG;IACH,yBAAyB,EAAE,OAAO,CAAC;IACnC;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CACf;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC9C,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;IACvC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B,GAAG,uBAAuB,CAsB1B"}

package/src/services/inference-capabilities.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+	defaultsForNoBinding,
+	probeCapabilities,
+	thermalThrottleDecision,
+} from "./inference-capabilities";
+
+describe("thermalThrottleDecision", () => {
+	it("does not throttle a cool device", () => {
+		const d = thermalThrottleDecision({ thermalState: "nominal" });
+		expect(d.throttleSpeculativeDecode).toBe(false);
+		expect(d.reduceLoad).toBe(false);
+	});
+
+	it("throttles speculative decode at serious and sheds load at critical", () => {
+		const serious = thermalThrottleDecision({ thermalState: "serious" });
+		expect(serious.throttleSpeculativeDecode).toBe(true);
+		expect(serious.reduceLoad).toBe(false);
+
+		const critical = thermalThrottleDecision({ thermalState: "critical" });
+		expect(critical.throttleSpeculativeDecode).toBe(true);
+		expect(critical.reduceLoad).toBe(true);
+	});
+
+	it("throttles under low-power mode even when cool", () => {
+		const d = thermalThrottleDecision({
+			thermalState: "nominal",
+			lowPowerMode: true,
+		});
+		expect(d.throttleSpeculativeDecode).toBe(true);
+		expect(d.reduceLoad).toBe(false);
+	});
+
+	it("does not throttle on an unknown thermal state without a low-power signal", () => {
+		const d = thermalThrottleDecision({ thermalState: "unknown" });
+		expect(d.throttleSpeculativeDecode).toBe(false);
+		expect(d.reduceLoad).toBe(false);
+	});
+
+	it("still honours low-power mode when thermal state is unknown", () => {
+		const d = thermalThrottleDecision({
+			thermalState: "unknown",
+			lowPowerMode: true,
+		});
+		expect(d.throttleSpeculativeDecode).toBe(true);
+	});
+});
+
+describe("probeCapabilities thermal gating (regression)", () => {
+	const probes = {
+		llmStreamSupported: () => true,
+		ttsStreamSupported: () => false,
+		mtpResident: () => true,
+		mmprojResident: () => false,
+		platform: () => "ios" as const,
+	};
+
+	it("keeps MTP on while cool but disables it under serious heat", () => {
+		expect(
+			probeCapabilities({ ...probes, thermalState: () => "fair" }).mtpSupported,
+		).toBe(true);
+		expect(
+			probeCapabilities({ ...probes, thermalState: () => "serious" })
+				.mtpSupported,
+		).toBe(false);
+	});
+
+	it("defaultsForNoBinding reports a safe all-off struct", () => {
+		const d = defaultsForNoBinding();
+		expect(d.streamingLlm).toBe(false);
+		expect(d.mtpSupported).toBe(false);
+		expect(d.thermalState).toBe("nominal");
+		expect(d.platform).toBe("unknown");
+	});
+});