@elizaos/app-core 2.0.0-alpha.70 → 2.0.0-alpha.71

package/.turbo/turbo-build.log

@@ -2,3 +2,4 @@ $ bun run build:dist
 $ test -f ../ui/dist/index.d.ts || (cd ../ui && bun run build) && rimraf dist && tsc -p tsconfig.build.json && node ../../scripts/copy-package-assets.mjs packages/app-core src/styles src/i18n/locales && node ../../scripts/prepare-package-dist.mjs packages/app-core
 error: Script not found "build"
 error: script "build:dist" exited with code 1
+error: script "build" exited with code 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/app-core",
-  "version": "2.0.0-alpha.70",
+  "version": "2.0.0-alpha.71",
   "description": "Shared application core for Milady shells and white-label apps.",
   "type": "module",
   "license": "MIT",
@@ -68,8 +68,8 @@
     "@capacitor/haptics": "8.0.0",
     "@capacitor/keyboard": "8.0.0",
     "@capacitor/preferences": "^8.0.1",
-    "@elizaos/autonomous": "2.0.0-alpha.70",
-    "@elizaos/ui": "2.0.0-alpha.70",
+    "@elizaos/autonomous": "2.0.0-alpha.71",
+    "@elizaos/ui": "2.0.0-alpha.71",
     "@sparkjsdev/spark": "^0.1.10",
     "lucide-react": "^0.575.0",
     "three": "^0.182.0",
@@ -87,5 +87,5 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "db049debacc33857bcea596057f1284568a061ff"
+  "gitHead": "c150a8cf4bffddd7e934f3a6073a092ca1cd6520"
 }

package/src/api/client.ts

@@ -5652,5 +5652,8 @@ export class MiladyClient {
   }
 }
 
+/** @deprecated Use MiladyClient directly. */
+export type ElizaClient = MiladyClient;
+
 // Singleton
 export const client = new MiladyClient();

package/src/bridge/electrobun-rpc.ts

@@ -47,6 +47,7 @@ export interface DetectedProvider {
   apiKey?: string;
   authMode?: string;
   cliInstalled: boolean;
+  status?: string;
 }
 
 export async function scanProviderCredentials(): Promise<DetectedProvider[]> {

package/src/components/FlaminaGuide.tsx

@@ -177,7 +177,7 @@ export function DeferredSetupChecklist({
       </div>
 
       <div className="space-y-2">
-        {onboardingDeferredTasks.map((task) => (
+        {(onboardingDeferredTasks as FlaminaGuideTopic[]).map((task) => (
           <div
             key={task}
             className="flex flex-col gap-2 rounded-xl border border-border/50 bg-bg/50 px-3 py-3 md:flex-row md:items-center md:justify-between"
@@ -199,7 +199,7 @@ export function DeferredSetupChecklist({
               <button
                 type="button"
                 className="rounded-full border border-border/60 px-3 py-1.5 text-[11px] font-semibold uppercase tracking-[0.12em] text-muted transition-colors hover:text-txt"
-                onClick={() => markDone(task)}
+                onClick={() => markDone(task as FlaminaGuideTopic)}
               >
                 Done
               </button>

package/src/components/avatar/VrmEngine.ts

@@ -838,6 +838,9 @@ export class VrmEngine {
     if (!this.scene || !this.renderer) return;
 
     const { SparkRenderer } = await this.loadSparkModule();
+    // Re-check after async import — the engine may have been disposed during
+    // the await (e.g. React StrictMode double-mount).
+    if (!this.scene || !this.renderer) return;
     const sparkRenderer = new SparkRenderer({
       renderer: this.renderer as THREE.WebGLRenderer,
       apertureAngle: 0.0,
@@ -1911,7 +1914,11 @@ export class VrmEngine {
     }
 
     await this.ensureSparkRenderer();
+    // Re-check after async — the engine may have been disposed during the
+    // await (e.g. React StrictMode double-mount or rapid navigation).
+    if (!this.scene || this.loadingAborted || requestId !== this.worldLoadRequestId) return;
     const spark = await this.loadSparkModule();
+    if (!this.scene || this.loadingAborted || requestId !== this.worldLoadRequestId) return;
     const { SplatMesh } = spark;
     let worldAnchor = new THREE.Vector3(0, 0, 0);
     let worldRevealRadius = 1;

package/src/components/avatar/VrmViewer.tsx

@@ -5,8 +5,8 @@
  * the `mouthOpen` prop. Sized to fill its parent container.
  */
 
-import { resolveAppAssetUrl } from "@elizaos/app-core/utils";
 import { useEffect, useEffectEvent, useRef } from "react";
+import { getVrmUrl } from "../../state/vrm";
 import {
   type CameraProfile,
   type InteractionMode,
@@ -15,7 +15,7 @@ import {
   type VrmEngineState,
 } from "./VrmEngine";
 
-const DEFAULT_VRM_PATH = resolveAppAssetUrl("vrms/eliza-1.vrm.gz");
+const DEFAULT_VRM_PATH = getVrmUrl(1);
 
 export type VrmViewerProps = {
   /** When false the loaded scene stays resident but the render loop is paused */

package/src/components/onboarding/ConnectionStep.tsx

@@ -293,17 +293,19 @@ export function ConnectionStep() {
     }
   };
 
-  // On native (mobile), force sandbox mode — skip straight to Eliza Cloud login.
-  // Mobile cannot run a local backend, so cloud is the only option.
+  // On native (mobile) or when branding requires cloud-only, force sandbox mode
+  // — skip straight to Eliza Cloud login. These platforms cannot run a local
+  // backend, so cloud is the only option.
+  const forceCloud = isNative || branding.cloudOnly;
   useEffect(() => {
-    if (isNative && !onboardingRunMode) {
+    if (forceCloud && !onboardingRunMode) {
       setState("onboardingRunMode", "cloud");
       setState("onboardingCloudProvider", "elizacloud");
       setState("onboardingProvider", "");
       setState("onboardingApiKey", "");
       setState("onboardingPrimaryModel", "");
     }
-  }, [isNative, onboardingRunMode, setState]);
+  }, [forceCloud, onboardingRunMode, setState]);
 
   if (!showProviderSelection) {
     if (!onboardingRunMode) {
@@ -319,7 +321,7 @@ export function ConnectionStep() {
             {t("onboarding.hostingQuestion")}
           </div>
           <div className="onboarding-provider-grid">
-            {!isNative && (
+            {!isNative && !branding.cloudOnly && (
               <button
                 type="button"
                 className="onboarding-provider-card onboarding-provider-card--recommended"

package/src/components/onboarding/OnboardingStepNav.tsx

@@ -6,11 +6,14 @@ export function OnboardingStepNav() {
   const branding = useBranding();
 
   const isEliza = branding.appName === "Eliza";
+  const isCloudOnly = !!branding.cloudOnly;
   const activeSteps = isEliza
     ? ONBOARDING_STEPS.filter(
         (s) => s.id === "connection" || s.id === "activate",
       )
-    : ONBOARDING_STEPS;
+    : isCloudOnly
+      ? ONBOARDING_STEPS.filter((s) => s.id !== "wakeUp")
+      : ONBOARDING_STEPS;
 
   const currentIndex = activeSteps.findIndex((s) => s.id === onboardingStep);
 

package/src/config/branding.ts

@@ -43,6 +43,8 @@ export interface BrandingConfig {
   packageScope: string;
   /** Custom providers injected by the app into the onboarding flow */
   customProviders?: CustomProviderOption[];
+  /** When true, the app requires Eliza Cloud — local backend mode is disabled. */
+  cloudOnly?: boolean;
 }
 
 export const DEFAULT_BRANDING: BrandingConfig = {

package/src/hooks/useMiladyBar.ts

@@ -18,10 +18,10 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   type DetectedProvider,
   invokeDesktopBridgeRequest,
-  scanAndValidateProviderCredentials,
   scanProviderCredentials,
   subscribeDesktopBridgeEvent,
 } from "../bridge/electrobun-rpc";
+import type { Tab } from "../navigation";
 import { isDesktopPlatform } from "../platform";
 import { useApp } from "../state";
 
@@ -423,8 +423,8 @@ export function useMiladyBar() {
   // Validated scan — for background refresh and manual refresh
   const runValidatedScan = useCallback(() => {
     if (!isDesktopPlatform()) return;
-    scanAndValidateProviderCredentials()
-      .then((results) => {
+    scanProviderCredentials()
+      .then((results: DetectedProvider[]) => {
         setScannedProviders(results);
         setLastRefreshAt(Date.now());
         setNow(Date.now());
@@ -514,7 +514,7 @@ export function useMiladyBar() {
         }
         if (itemId.startsWith("navigate-")) {
           const target = itemId.replace("navigate-", "");
-          setTab?.(target);
+          setTab?.(target as Tab);
           void invokeDesktopBridgeRequest({
             rpcMethod: "desktopShowWindow",
             ipcChannel: "desktop:showWindow",

package/src/state/AppContext.tsx

@@ -14,6 +14,7 @@ import {
   useState,
 } from "react";
 import { prepareDraftForSave } from "../actions/character";
+import { BrandingContext, DEFAULT_BRANDING } from "../config/branding";
 import {
   type AgentStartupDiagnostics,
   type AgentStatus,
@@ -424,7 +425,13 @@ function getFlaminaTopicForOnboardingStep(
 
 // ── Provider ───────────────────────────────────────────────────────────
 
-export function AppProvider({ children }: { children: ReactNode }) {
+export function AppProvider({
+  children,
+  branding: brandingOverride,
+}: {
+  children: ReactNode;
+  branding?: Partial<import("../config/branding").BrandingConfig>;
+}) {
   const [lastNativeTab, setLastNativeTabState] =
     useState<Tab>(loadLastNativeTab);
   // --- Core state ---
@@ -804,7 +811,9 @@ export function AppProvider({ children }: { children: ReactNode }) {
 
   // --- Onboarding ---
   const [onboardingStep, setOnboardingStepRaw] = useState<OnboardingStep>(
-    () => loadPersistedOnboardingStep() ?? "wakeUp",
+    () =>
+      loadPersistedOnboardingStep() ??
+      (brandingOverride?.cloudOnly ? "identity" : "wakeUp"),
   );
   const [onboardingMode, setOnboardingMode] =
     useState<AppState["onboardingMode"]>("basic");
@@ -826,8 +835,10 @@ export function AppProvider({ children }: { children: ReactNode }) {
   const [onboardingStyle, setOnboardingStyle] = useState("");
   const [onboardingRunMode, setOnboardingRunMode] = useState<
     "local" | "cloud" | ""
-  >("");
-  const [onboardingCloudProvider, setOnboardingCloudProvider] = useState("");
+  >(brandingOverride?.cloudOnly ? "cloud" : "");
+  const [onboardingCloudProvider, setOnboardingCloudProvider] = useState(
+    brandingOverride?.cloudOnly ? "elizacloud" : "",
+  );
   const [onboardingSmallModel, setOnboardingSmallModel] = useState(
     "moonshotai/kimi-k2-turbo",
   );
@@ -2201,7 +2212,8 @@ export function AppProvider({ children }: { children: ReactNode }) {
 
   const notifyHeartbeatEvent = useCallback(
     (event: StreamEventEnvelope) => {
-      const payload = event.payload;
+      // biome-ignore lint/suspicious/noExplicitAny: heartbeat payloads are loosely typed
+      const payload = event.payload as any;
       const status =
         typeof payload.status === "string"
           ? payload.status.trim().toLowerCase()
@@ -4020,7 +4032,7 @@ export function AppProvider({ children }: { children: ReactNode }) {
     setCharacterSaveSuccess(null);
     try {
       const draft = prepareDraftForSave(characterDraft);
-      if (!draft.name?.trim()) {
+      if (!(draft.name as string | undefined)?.trim()) {
         throw new Error("Character name is required before saving.");
       }
       const { agentName } = await client.updateCharacter(draft);
@@ -4214,13 +4226,13 @@ export function AppProvider({ children }: { children: ReactNode }) {
       if (isSandboxMode) {
         // Provision a sandbox agent on Eliza Cloud
         const cloudApiBase = (
-          (window as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__ ??
+          (window as unknown as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__ ??
           "https://api.eliza.ai"
         ) as string;
 
         // Get the auth token from the cloud login state
         const authToken = (
-          (window as Record<string, unknown>).__ELIZA_CLOUD_AUTH_TOKEN__ ?? ""
+          (window as unknown as Record<string, unknown>).__ELIZA_CLOUD_AUTH_TOKEN__ ?? ""
         ) as string;
 
         if (!authToken) {
@@ -4229,7 +4241,7 @@ export function AppProvider({ children }: { children: ReactNode }) {
           );
         }
 
-        const { bridgeUrl } = await client.provisionCloudSandbox({
+        await client.provisionCloudSandbox({
           cloudApiBase,
           authToken,
           name: onboardingName,
@@ -4257,9 +4269,12 @@ export function AppProvider({ children }: { children: ReactNode }) {
             ipcChannel: "agent:start",
           });
         } catch {
-          // May not be on desktop — try the Capacitor agent plugin fallback
+          // May not be on desktop — try the Capacitor agent plugin fallback.
+          // Use a variable to prevent Vite static analysis from failing on
+          // this optional peer dependency (only available in milady app builds).
           try {
-            const { Agent } = await import("@miladyai/capacitor-agent");
+            const agentPluginId = "@miladyai/capacitor-agent";
+            const { Agent } = await import(/* @vite-ignore */ agentPluginId);
             await Agent.start();
           } catch {
             // Not on desktop or native — dev mode where agent is already running
@@ -4614,7 +4629,7 @@ export function AppProvider({ children }: { children: ReactNode }) {
     const hasBackend = Boolean(client.getBaseUrl());
     const cloudApiBase =
       ((typeof window !== "undefined" &&
-        (window as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__) as string) ||
+        (window as unknown as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__) as string) ||
       "https://api.eliza.ai";
     const useDirectAuth = !hasBackend;
 
@@ -4701,9 +4716,9 @@ export function AppProvider({ children }: { children: ReactNode }) {
 
             // Store the cloud auth token for provisioning
             if (poll.token && typeof window !== "undefined") {
-              (window as Record<string, unknown>).__ELIZA_CLOUD_AUTH_TOKEN__ =
+              (window as unknown as Record<string, unknown>).__ELIZA_CLOUD_AUTH_TOKEN__ =
                 poll.token;
-              (window as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__ =
+              (window as unknown as Record<string, unknown>).__ELIZA_CLOUD_API_BASE__ =
                 cloudApiBase;
             }
 
@@ -4786,6 +4801,11 @@ export function AppProvider({ children }: { children: ReactNode }) {
     }
   }, [setActionNotice]);
 
+  const handleCloudOnboardingFinish = useCallback(() => {
+    setOnboardingComplete(true);
+    setTab("chat");
+  }, []);
+
   // ── Updates ────────────────────────────────────────────────────────
 
   const handleChannelChange = useCallback(
@@ -5182,9 +5202,9 @@ export function AppProvider({ children }: { children: ReactNode }) {
       const persistedConnection = loadPersistedConnectionMode();
       const hasApiBase = Boolean(
         (typeof window !== "undefined" &&
-          (window as Record<string, unknown>).__MILADY_API_BASE__) ||
+          (window as unknown as Record<string, unknown>).__MILADY_API_BASE__) ||
           (typeof window !== "undefined" &&
-            (window as Record<string, unknown>).__ELIZA_API_BASE__),
+            (window as unknown as Record<string, unknown>).__ELIZA_API_BASE__),
       );
 
       if (!persistedConnection && !hasApiBase) {
@@ -5912,6 +5932,7 @@ export function AppProvider({ children }: { children: ReactNode }) {
       const shouldStartAtCharacterSelect = shouldStartAtCharacterSelectOnLaunch(
         {
           onboardingNeedsOptions,
+          onboardingMode,
           navPath,
           urlTab,
         },
@@ -6363,6 +6384,7 @@ export function AppProvider({ children }: { children: ReactNode }) {
     handleOnboardingUseLocalBackend,
     handleCloudLogin,
     handleCloudDisconnect,
+    handleCloudOnboardingFinish,
     loadUpdateStatus,
     handleChannelChange,
     checkExtensionStatus,
@@ -6376,11 +6398,18 @@ export function AppProvider({ children }: { children: ReactNode }) {
     copyToClipboard,
   };
 
+  const mergedBranding = useMemo(
+    () => ({ ...DEFAULT_BRANDING, ...brandingOverride }),
+    [brandingOverride],
+  );
+
   return (
-    <AppContext.Provider value={value}>
-      {children}
-      <ConfirmModal {...modalProps} />
-      <PromptModal {...promptModalProps} />
-    </AppContext.Provider>
+    <BrandingContext.Provider value={mergedBranding}>
+      <AppContext.Provider value={value}>
+        {children}
+        <ConfirmModal {...modalProps} />
+        <PromptModal {...promptModalProps} />
+      </AppContext.Provider>
+    </BrandingContext.Provider>
   );
 }

package/src/state/types.ts

@@ -109,8 +109,13 @@ export const ONBOARDING_STEPS: OnboardingStepMeta[] = [
   },
 ];
 
+export type OnboardingMode = "basic" | "advanced" | "elizacloudonly";
+
+export type FlaminaGuideTopic = "provider" | "rpc" | "permissions" | "voice";
+
 export interface OnboardingNextOptions {
   allowPermissionBypass?: boolean;
+  skipTask?: string;
 }
 
 export const ONBOARDING_PERMISSION_LABELS: Record<SystemPermissionId, string> =
@@ -431,8 +436,15 @@ export interface AppState {
   importError: string | null;
   importSuccess: string | null;
 
+  // Startup
+  startupStatus: string | null;
+
   // Onboarding
   onboardingStep: OnboardingStep;
+  onboardingMode: OnboardingMode;
+  onboardingActiveGuide: string | null;
+  onboardingDeferredTasks: string[];
+  postOnboardingChecklistDismissed: boolean;
   onboardingOptions: OnboardingOptions | null;
   onboardingName: string;
   onboardingOwnerName: string;
@@ -548,6 +560,8 @@ export interface AppActions {
   handleReset: () => Promise<void>;
   retryStartup: () => void;
   dismissRestartBanner: () => void;
+  showRestartBanner: () => void;
+  relaunchDesktop: () => Promise<void>;
   triggerRestart: () => Promise<void>;
   dismissBackendDisconnectedBanner: () => void;
   retryBackendConnection: () => void;
@@ -669,6 +683,7 @@ export interface AppActions {
   // Cloud
   handleCloudLogin: () => Promise<void>;
   handleCloudDisconnect: () => Promise<void>;
+  handleCloudOnboardingFinish: () => void;
 
   // Updates
   loadUpdateStatus: (force?: boolean) => Promise<void>;

package/src/state/vrm.ts

@@ -1,48 +1,82 @@
 import { resolveAppAssetUrl } from "../utils/asset-url";
 import type { UiTheme } from "./ui-preferences";
 
-/** Number of bundled VRM avatars shipped with the app. */
-const BASE_VRM_COUNT = 4;
+// ---------------------------------------------------------------------------
+// Bundled VRM asset roster
+// ---------------------------------------------------------------------------
 
-export const VRM_COUNT = BASE_VRM_COUNT;
+interface BundledVrmAsset {
+  title: string;
+  slug: string;
+}
 
 /**
- * Maps logical avatar indices (1-4) to the original source file numbers.
- * Index 1 → eliza-1, Index 2 → eliza-4, Index 3 → eliza-5, Index 4 → eliza-9.
+ * Default Eliza avatar roster (4 slots).
+ * Apps can override this at startup by setting window.__APP_VRM_ASSETS__
+ * before mounting the React tree.
  */
-const VRM_INDEX_MAP: readonly number[] = [1, 4, 5, 9];
+const DEFAULT_ASSETS: BundledVrmAsset[] = [
+  { title: "ELIZA-01", slug: "eliza-1" },
+  { title: "ELIZA-04", slug: "eliza-4" },
+  { title: "ELIZA-05", slug: "eliza-5" },
+  { title: "ELIZA-09", slug: "eliza-9" },
+];
 
-function resolveSourceIndex(logicalIndex: number): number {
-  const normalized = normalizeAvatarIndex(logicalIndex);
-  const safe = normalized > 0 ? normalized : 1;
-  return VRM_INDEX_MAP[safe - 1] ?? VRM_INDEX_MAP[0];
+declare global {
+  interface Window {
+    __APP_VRM_ASSETS__?: BundledVrmAsset[];
+  }
 }
 
-function normalizeAvatarIndex(index: number): number {
+function getAssets(): BundledVrmAsset[] {
+  if (typeof window !== "undefined" && Array.isArray(window.__APP_VRM_ASSETS__)) {
+    return window.__APP_VRM_ASSETS__;
+  }
+  return DEFAULT_ASSETS;
+}
+
+/** Number of bundled VRM avatars shipped with the app. */
+export function getVrmCount(): number {
+  return getAssets().length;
+}
+
+// Legacy constant — prefer getVrmCount() for dynamic rosters.
+export const VRM_COUNT = DEFAULT_ASSETS.length;
+
+export function normalizeAvatarIndex(index: number): number {
   if (!Number.isFinite(index)) return 1;
   const n = Math.trunc(index);
   if (n === 0) return 0;
-  if (n < 1 || n > VRM_COUNT) return 1;
+  const count = getAssets().length;
+  if (n < 1 || n > count) return 1;
   return n;
 }
 
 /** Resolve a bundled VRM index (1–N) to its public asset URL. */
 export function getVrmUrl(index: number): string {
-  const sourceIndex = resolveSourceIndex(index);
-  return resolveAppAssetUrl(`vrms/eliza-${sourceIndex}.vrm.gz`);
+  const assets = getAssets();
+  const n = normalizeAvatarIndex(index);
+  const safe = n > 0 ? n : 1;
+  const slug = assets[safe - 1]?.slug ?? assets[0].slug;
+  return resolveAppAssetUrl(`vrms/${slug}.vrm.gz`);
 }
 
 /** Resolve a bundled VRM index (1–N) to its preview thumbnail URL. */
 export function getVrmPreviewUrl(index: number): string {
-  const sourceIndex = resolveSourceIndex(index);
-  return resolveAppAssetUrl(`vrms/previews/eliza-${sourceIndex}.png`);
+  const assets = getAssets();
+  const n = normalizeAvatarIndex(index);
+  const safe = n > 0 ? n : 1;
+  const slug = assets[safe - 1]?.slug ?? assets[0].slug;
+  return resolveAppAssetUrl(`vrms/previews/${slug}.png`);
 }
 
 /** Resolve a bundled VRM index (1-N) to its custom background URL. */
 export function getVrmBackgroundUrl(index: number): string {
-  const sourceIndex = resolveSourceIndex(index);
-  const EXT = "png";
-  return resolveAppAssetUrl(`vrms/backgrounds/eliza-${sourceIndex}.${EXT}`);
+  const assets = getAssets();
+  const n = normalizeAvatarIndex(index);
+  const safe = n > 0 ? n : 1;
+  const slug = assets[safe - 1]?.slug ?? assets[0].slug;
+  return resolveAppAssetUrl(`vrms/backgrounds/${slug}.png`);
 }
 
 const COMPANION_THEME_BACKGROUND_INDEX: Record<UiTheme, number> = {
@@ -57,8 +91,10 @@ export function getCompanionBackgroundUrl(theme: UiTheme): string {
 
 /** Human-readable roster title for bundled avatars. */
 export function getVrmTitle(index: number): string {
-  const sourceIndex = resolveSourceIndex(index);
-  return `ELIZA-${String(sourceIndex).padStart(2, "0")}`;
+  const assets = getAssets();
+  const n = normalizeAvatarIndex(index);
+  const safe = n > 0 ? n : 1;
+  return assets[safe - 1]?.title ?? assets[0].title;
 }
 
 /** Whether a bundled index points to the official Eliza avatar set. */
@@ -67,10 +103,6 @@ export function isOfficialVrmIndex(_index: number): boolean {
 }
 
 /** Whether a VRM index requires an explicit 180° face-camera flip instead of auto-detection. */
-export function getVrmNeedsFlip(index: number): boolean {
-  const normalized = normalizeAvatarIndex(index);
-  if (normalized <= BASE_VRM_COUNT) return false;
+export function getVrmNeedsFlip(_index: number): boolean {
   return false;
 }
-
-export { normalizeAvatarIndex };

package/test/app/cloud-login-lock.test.ts

@@ -54,6 +54,7 @@ const { mockClient } = vi.hoisted(() => ({
       triggers: [],
       todos: [],
     })),
+    getBaseUrl: vi.fn(() => "http://localhost:2138"),
     cloudLogin: vi.fn(async () => ({
       ok: false,
       browserUrl: "",
@@ -126,6 +127,9 @@ describe("cloud login locking", () => {
       setInterval: globalThis.setInterval,
       clearInterval: globalThis.clearInterval,
       open: vi.fn(() => null),
+      // Simulate an available backend so the startup flow doesn't skip to
+      // fresh-install onboarding immediately.
+      __MILADY_API_BASE__: "http://localhost:2138",
     });
     Object.assign(document.documentElement, { setAttribute: vi.fn() });
 

package/test/app/connection-mode-persistence.test.ts

@@ -0,0 +1,411 @@
+// @vitest-environment jsdom
+
+/**
+ * Tests for the PersistedConnectionMode persistence layer and
+ * startup fresh-install detection added in the onboarding/connection rework.
+ *
+ * Covers:
+ * - Persistence save/load/clear round-trips
+ * - Fresh install detection (no persisted mode + no API base → skip backend polling)
+ * - Returning user restoration (persisted mode restores client connection)
+ * - Mobile sandbox-only enforcement
+ * - Cloud provisioning client method
+ * - Connection key auto-generation (milady-side)
+ * - Direct cloud auth (no backend path)
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the API client at top level to avoid hoisting warnings
+const { mockClient } = vi.hoisted(() => ({
+  mockClient: {
+    hasToken: vi.fn(() => false),
+    getAuthStatus: vi.fn(async () => ({
+      required: false,
+      pairingEnabled: false,
+      expiresAt: null,
+    })),
+    getOnboardingStatus: vi.fn(async () => ({ complete: false })),
+    disconnectWs: vi.fn(),
+    getCodingAgentStatus: vi.fn(async () => null),
+    setToken: vi.fn(),
+  },
+}));
+
+vi.mock("@elizaos/app-core/api", () => ({
+  client: mockClient,
+  SkillScanReportSummary: {},
+}));
+
+// ── Persistence layer tests ────────────────────────────────────────────
+
+describe("PersistedConnectionMode persistence", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("returns null when no connection mode is persisted", async () => {
+    const { loadPersistedConnectionMode } = await import(
+      "../../src/state/persistence"
+    );
+    expect(loadPersistedConnectionMode()).toBeNull();
+  });
+
+  it("round-trips a local connection mode", async () => {
+    const { loadPersistedConnectionMode, savePersistedConnectionMode } =
+      await import("../../src/state/persistence");
+
+    savePersistedConnectionMode({ runMode: "local" });
+    const loaded = loadPersistedConnectionMode();
+    expect(loaded).toEqual({ runMode: "local" });
+  });
+
+  it("round-trips a cloud connection mode with auth", async () => {
+    const { loadPersistedConnectionMode, savePersistedConnectionMode } =
+      await import("../../src/state/persistence");
+
+    savePersistedConnectionMode({
+      runMode: "cloud",
+      cloudApiBase: "https://api.eliza.ai",
+      cloudAuthToken: "token-123",
+    });
+    const loaded = loadPersistedConnectionMode();
+    expect(loaded).toEqual({
+      runMode: "cloud",
+      cloudApiBase: "https://api.eliza.ai",
+      cloudAuthToken: "token-123",
+    });
+  });
+
+  it("round-trips a remote connection mode", async () => {
+    const { loadPersistedConnectionMode, savePersistedConnectionMode } =
+      await import("../../src/state/persistence");
+
+    savePersistedConnectionMode({
+      runMode: "remote",
+      remoteApiBase: "https://my-agent.example.com",
+      remoteAccessToken: "key-abc",
+    });
+    const loaded = loadPersistedConnectionMode();
+    expect(loaded).toEqual({
+      runMode: "remote",
+      remoteApiBase: "https://my-agent.example.com",
+      remoteAccessToken: "key-abc",
+    });
+  });
+
+  it("clears persisted connection mode", async () => {
+    const {
+      clearPersistedConnectionMode,
+      loadPersistedConnectionMode,
+      savePersistedConnectionMode,
+    } = await import("../../src/state/persistence");
+
+    savePersistedConnectionMode({ runMode: "local" });
+    expect(loadPersistedConnectionMode()).not.toBeNull();
+
+    clearPersistedConnectionMode();
+    expect(loadPersistedConnectionMode()).toBeNull();
+  });
+
+  it("returns null for corrupted JSON", async () => {
+    const { loadPersistedConnectionMode } = await import(
+      "../../src/state/persistence"
+    );
+
+    localStorage.setItem("eliza:connection-mode", "not-json{{{");
+    expect(loadPersistedConnectionMode()).toBeNull();
+  });
+
+  it("returns null for invalid runMode value", async () => {
+    const { loadPersistedConnectionMode } = await import(
+      "../../src/state/persistence"
+    );
+
+    localStorage.setItem(
+      "eliza:connection-mode",
+      JSON.stringify({ runMode: "invalid" }),
+    );
+    expect(loadPersistedConnectionMode()).toBeNull();
+  });
+
+  it("returns null for non-object stored value", async () => {
+    const { loadPersistedConnectionMode } = await import(
+      "../../src/state/persistence"
+    );
+
+    localStorage.setItem("eliza:connection-mode", JSON.stringify([1, 2, 3]));
+    expect(loadPersistedConnectionMode()).toBeNull();
+  });
+});
+
+// ── Fresh install detection ────────────────────────────────────────────
+
+describe("fresh install detection (startup)", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    delete (window as Record<string, unknown>).__MILADY_API_BASE__;
+    delete (window as Record<string, unknown>).__ELIZA_API_BASE__;
+    Object.assign(document.documentElement, { setAttribute: vi.fn() });
+  });
+
+  it("skips backend polling on fresh install (no persisted mode, no API base)", async () => {
+    const React = await import("react");
+    const TestRenderer = await import("react-test-renderer");
+    const { AppProvider, useApp } = await import("@elizaos/app-core/state");
+
+    let latest: {
+      onboardingComplete: boolean;
+      onboardingLoading: boolean;
+      startupPhase: string;
+      startupError: unknown;
+    } | null = null;
+
+    function Probe() {
+      const app = useApp();
+      React.useEffect(() => {
+        latest = {
+          onboardingComplete: app.onboardingComplete,
+          onboardingLoading: app.onboardingLoading,
+          startupPhase: app.startupPhase,
+          startupError: app.startupError,
+        };
+      });
+      return null;
+    }
+
+    let tree: TestRenderer.ReactTestRenderer | null = null;
+    await TestRenderer.act(async () => {
+      tree = TestRenderer.create(
+        React.createElement(AppProvider, null, React.createElement(Probe)),
+      );
+    });
+
+    await TestRenderer.act(async () => {
+      await Promise.resolve();
+    });
+
+    // On fresh install: should immediately be ready for onboarding
+    // without waiting for a backend
+    expect(latest).not.toBeNull();
+    expect(latest!.onboardingComplete).toBe(false);
+    expect(latest!.onboardingLoading).toBe(false);
+    expect(latest!.startupError).toBeNull();
+
+    // The backend should NOT have been polled
+    expect(mockClient.getAuthStatus).not.toHaveBeenCalled();
+    expect(mockClient.getOnboardingStatus).not.toHaveBeenCalled();
+
+    await TestRenderer.act(async () => {
+      tree?.unmount();
+    });
+  });
+});
+
+// ── API client cloud provisioning ──────────────────────────────────────
+
+describe("MiladyClient.provisionCloudSandbox", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("provisions a sandbox agent through create → provision → poll", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    const fetchMock = vi.fn();
+
+    // Create agent response
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "agent-1" }),
+    });
+    // Provision response
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ jobId: "job-1" }),
+    });
+    // Poll - still pending
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ status: "in_progress" }),
+    });
+    // Poll - completed
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        status: "completed",
+        result: { bridgeUrl: "https://bridge.eliza.ai/agent-1" },
+      }),
+    });
+
+    globalThis.fetch = fetchMock;
+
+    const progressUpdates: string[] = [];
+    const result = await client.provisionCloudSandbox({
+      cloudApiBase: "https://api.eliza.ai",
+      authToken: "token-123",
+      name: "TestAgent",
+      onProgress: (status) => progressUpdates.push(status),
+    });
+
+    expect(result.bridgeUrl).toBe("https://bridge.eliza.ai/agent-1");
+    expect(result.agentId).toBe("agent-1");
+    expect(progressUpdates).toContain("creating");
+    expect(progressUpdates).toContain("provisioning");
+    expect(progressUpdates).toContain("ready");
+
+    // Verify API calls
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+    expect(fetchMock.mock.calls[0][0]).toBe(
+      "https://api.eliza.ai/api/v1/milady/agents",
+    );
+    expect(fetchMock.mock.calls[1][0]).toBe(
+      "https://api.eliza.ai/api/v1/milady/agents/agent-1/provision",
+    );
+  });
+
+  it("throws on provisioning failure", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    const fetchMock = vi.fn();
+
+    // Create succeeds
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "agent-1" }),
+    });
+    // Provision succeeds
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ jobId: "job-1" }),
+    });
+    // Poll - failed
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        status: "failed",
+        error: "Insufficient credits",
+      }),
+    });
+
+    globalThis.fetch = fetchMock;
+
+    await expect(
+      client.provisionCloudSandbox({
+        cloudApiBase: "https://api.eliza.ai",
+        authToken: "token-123",
+        name: "TestAgent",
+      }),
+    ).rejects.toThrow("Provisioning failed: Insufficient credits");
+  });
+
+  it("throws on agent creation failure", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      text: async () => "Unauthorized",
+    });
+
+    await expect(
+      client.provisionCloudSandbox({
+        cloudApiBase: "https://api.eliza.ai",
+        authToken: "bad-token",
+        name: "TestAgent",
+      }),
+    ).rejects.toThrow("Failed to create cloud agent: Unauthorized");
+  });
+});
+
+// ── Direct cloud auth ──────────────────────────────────────────────────
+
+describe("MiladyClient direct cloud auth", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("cloudLoginDirect calls the cloud API directly", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        ok: true,
+        browserUrl: "https://eliza.ai/login?session=abc",
+        sessionId: "abc",
+      }),
+    });
+
+    const result = await client.cloudLoginDirect("https://api.eliza.ai");
+    expect(result.ok).toBe(true);
+    expect(result.sessionId).toBe("abc");
+    expect(result.browserUrl).toContain("login");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.eliza.ai/api/v1/auth/login",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
+  it("cloudLoginPollDirect polls the cloud API directly", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        status: "authenticated",
+        token: "auth-token-xyz",
+        userId: "user-1",
+      }),
+    });
+
+    const result = await client.cloudLoginPollDirect(
+      "https://api.eliza.ai",
+      "session-123",
+    );
+    expect(result.status).toBe("authenticated");
+    expect(result.token).toBe("auth-token-xyz");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.eliza.ai/api/v1/auth/login/status?sessionId=session-123",
+    );
+  });
+
+  it("cloudLoginDirect returns error on failure", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://localhost:2138");
+
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+    });
+
+    const result = await client.cloudLoginDirect("https://api.eliza.ai");
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("500");
+  });
+});
+
+// ── API client getBaseUrl ──────────────────────────────────────────────
+
+describe("MiladyClient.getBaseUrl", () => {
+  it("returns the current base URL", async () => {
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient("http://my-agent.example.com");
+    expect(client.getBaseUrl()).toBe("http://my-agent.example.com");
+  });
+
+  it("returns empty string when no base URL is configured", async () => {
+    // In jsdom with about:blank protocol, no injected base
+    delete (window as Record<string, unknown>).__MILADY_API_BASE__;
+    const { MiladyClient } = await import("../../src/api/client");
+    const client = new MiladyClient();
+    // May return "" or a fallback depending on window.location.protocol
+    expect(typeof client.getBaseUrl()).toBe("string");
+  });
+});

package/test/app/onboarding-finish-lock.test.ts

@@ -237,6 +237,9 @@ describe("onboarding finish locking", () => {
       setInterval: globalThis.setInterval,
       clearInterval: globalThis.clearInterval,
       alert: vi.fn(),
+      // Simulate an available backend so the startup flow doesn't skip to
+      // onboarding immediately (fresh install detection).
+      __MILADY_API_BASE__: "http://localhost:2138",
     });
     Object.assign(document.documentElement, { setAttribute: vi.fn() });
     localStorage.clear();

package/test/app/startup-backend-missing.e2e.test.ts

@@ -53,6 +53,13 @@ describe("startup failure: backend missing", () => {
   beforeEach(() => {
     vi.useFakeTimers();
     Object.assign(document.documentElement, { setAttribute: vi.fn() });
+    // Simulate a returning user with a persisted local connection so the
+    // startup flow proceeds to backend polling (fresh installs now skip
+    // backend polling and go straight to onboarding).
+    localStorage.setItem(
+      "eliza:connection-mode",
+      JSON.stringify({ runMode: "local" }),
+    );
     mockClient.hasToken.mockReturnValue(false);
     mockClient.disconnectWs.mockImplementation(() => {});
     mockClient.getAuthStatus.mockResolvedValue({
@@ -73,6 +80,7 @@ describe("startup failure: backend missing", () => {
 
   afterEach(() => {
     vi.useRealTimers();
+    localStorage.removeItem("eliza:connection-mode");
   });
 
   it("fails fast on backend 404 and surfaces backend-unreachable", async () => {