@elizaos/ui 2.0.0-alpha.85 → 2.0.0-beta.2

package/state/useOnboardingCallbacks.js

@@ -0,0 +1,804 @@
+/**
+ * Onboarding callbacks — extracted from AppContext.
+ *
+ * Holds all the callback functions for the onboarding flow:
+ * completeOnboarding, runOnboardingChatHandoff, handleOnboardingFinish,
+ * advanceOnboarding / handleOnboardingNext, revertOnboarding /
+ * handleOnboardingBack, handleOnboardingJumpToStep, goToOnboardingStep,
+ * applyResetConnectionWizardToHostingStep, handleCloudOnboardingFinish,
+ * handleOnboardingUseLocalBackend, handleOnboardingRemoteConnect,
+ * and applyDetectedProviders.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { Capacitor } from "@capacitor/core";
+import { buildWalletRpcUpdateRequest, getDefaultStylePreset, } from "@elizaos/shared";
+import { useCallback } from "react";
+import { ElizaClient } from "../api/index.js";
+const ensureOnboardedAgentRunning = async (client) => {
+    try {
+        const status = await client.getStatus();
+        if (status?.state !== "running" && status?.state !== "starting") {
+            await client.startAgent();
+        }
+    }
+    catch {
+        // Non-fatal: agent manager may not be ready yet. Onboarding will retry.
+    }
+};
+async function startNativeAgentIfAvailable() {
+    try {
+        const capacitorWithPlugins = Capacitor;
+        const registeredAgent = capacitorWithPlugins.Plugins?.Agent ??
+            Capacitor.registerPlugin("Agent");
+        await registeredAgent.start?.();
+    }
+    catch {
+        const agentPluginId = "@elizaos/capacitor-agent";
+        const { Agent } = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ agentPluginId));
+        await Agent?.start?.();
+    }
+}
+import { getDesktopRuntimeMode, invokeDesktopBridgeRequest, } from "../bridge/index.js";
+import { getBootConfig } from "../config/boot-config.js";
+import { APPS_ENABLED, COMPANION_ENABLED } from "../navigation/index.js";
+import { canRevertOnboardingTo, getFlaminaTopicForOnboardingStep, getOnboardingStepIndex, resolveOnboardingNextStep, resolveOnboardingPreviousStep, shouldSkipConnectionStepsForCloudProvisionedContainer, shouldSkipFeaturesStep, shouldUseCloudOnboardingFastTrack, } from "../onboarding/flow.js";
+import { persistMobileRuntimeModeForServerTarget } from "../onboarding/mobile-runtime-mode.js";
+import { isElizaCloudOnboardingTarget } from "../onboarding/server-target.js";
+import { buildOnboardingRuntimeConfig } from "../onboarding-config.js";
+import { PREMADE_VOICES } from "../voice/types.js";
+import { clearPersistedActiveServer, clearPersistedOnboardingStep, createPersistedActiveServer, savePersistedActiveServer, } from "./internal.js";
+// ── Helpers copied from AppContext (module-level, no React deps) ──────────
+function isPrivateNetworkHost(host) {
+    if (host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "::1" ||
+        host.endsWith(".local") ||
+        host.endsWith(".internal")) {
+        return true;
+    }
+    if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host))
+        return true;
+    if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(host))
+        return true;
+    if (/^172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(host))
+        return true;
+    if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3}$/.test(host)) {
+        return true;
+    }
+    return false;
+}
+function replaceNavigationPathForCompanionLaunch() {
+    if (typeof window === "undefined")
+        return;
+    const path = "/apps/companion";
+    try {
+        if (window.location.protocol === "file:") {
+            window.location.hash = path;
+        }
+        else {
+            window.history.replaceState(null, "", `${path}${window.location.search}${window.location.hash}`);
+        }
+    }
+    catch {
+        /* ignore — sandboxed iframe */
+    }
+}
+function normalizeRemoteApiBaseInput(rawValue) {
+    const trimmed = rawValue.trim();
+    if (!trimmed) {
+        throw new Error("Enter a backend address.");
+    }
+    const hasScheme = /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(trimmed);
+    const hostGuess = trimmed.replace(/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//, "");
+    const guessedHost = hostGuess.split("/")[0]?.replace(/:\d+$/, "") ?? "";
+    const defaultProtocol = isPrivateNetworkHost(guessedHost) ? "http" : "https";
+    const candidate = hasScheme ? trimmed : `${defaultProtocol}://${trimmed}`;
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        throw new Error("Enter a valid backend address.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Remote backends must use http:// or https://.");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/+$/, "");
+}
+function resolveSelectedOnboardingStyle(args) {
+    const styles = args.styles ?? [];
+    return (styles.find((style) => style.id === args.onboardingStyle) ??
+        styles.find((style) => typeof style.avatarIndex === "number" &&
+            style.avatarIndex === args.selectedVrmIndex) ??
+        styles[0] ??
+        getDefaultStylePreset(args.uiLanguage));
+}
+export function buildOnboardingStyleVoiceConfig(args) {
+    const { style, voiceProvider, voiceApiKey, cloudTtsSelected } = args;
+    const voicePresetId = style?.voicePresetId?.trim();
+    if (!voicePresetId) {
+        return null;
+    }
+    const presetVoice = PREMADE_VOICES.find((voice) => voice.id === voicePresetId);
+    if (!presetVoice) {
+        return null;
+    }
+    const trimmedVoiceApiKey = voiceApiKey.trim();
+    const mode = voiceProvider === "elevenlabs" && trimmedVoiceApiKey
+        ? "own-key"
+        : cloudTtsSelected
+            ? "cloud"
+            : undefined;
+    return {
+        provider: "elevenlabs",
+        ...(mode ? { mode } : {}),
+        elevenlabs: {
+            voiceId: presetVoice.voiceId,
+            ...(mode === "own-key" ? { apiKey: trimmedVoiceApiKey } : {}),
+        },
+    };
+}
+async function persistOnboardingStyleVoice(args) {
+    const voiceConfig = buildOnboardingStyleVoiceConfig(args);
+    if (!voiceConfig) {
+        return;
+    }
+    await args.clientRef.updateConfig({
+        messages: {
+            tts: voiceConfig,
+        },
+    });
+}
+export function buildOnboardingFeatureSubmitPayload(args) {
+    const connectors = args.onboardingFeatureTelegram || args.onboardingFeatureDiscord
+        ? {
+            ...(args.onboardingFeatureTelegram
+                ? { telegram: { enabled: true, managed: true } }
+                : {}),
+            ...(args.onboardingFeatureDiscord
+                ? { discord: { enabled: true, managed: true } }
+                : {}),
+        }
+        : undefined;
+    const featureEntries = {};
+    if (args.onboardingFeatureBrowser)
+        featureEntries.browser = { enabled: true };
+    if (args.onboardingFeatureComputerUse)
+        featureEntries.computeruse = { enabled: true };
+    const features = Object.keys(featureEntries).length > 0 ? featureEntries : undefined;
+    return {
+        ...(connectors ? { connectors } : {}),
+        ...(features ? { features } : {}),
+    };
+}
+// ── Hook ──────────────────────────────────────────────────────────────────
+export function useOnboardingCallbacks(deps) {
+    const { onboarding, setActiveOverlayApp, setOnboardingStep, setOnboardingMode: _setOnboardingMode, setOnboardingActiveGuide, setOnboardingDetectedProviders, setOnboardingServerTarget, setOnboardingCloudApiKey, setOnboardingProvider, setOnboardingApiKey, setOnboardingPrimaryModel: _setOnboardingPrimaryModel, setOnboardingRemoteApiBase, setOnboardingRemoteToken, setOnboardingRemoteConnecting, setOnboardingRemoteError, setOnboardingRemoteConnected, setPostOnboardingChecklistDismissed, setBrowserEnabled, setComputerUseEnabled, setOnboardingComplete, coordinatorOnboardingCompleteRef, initialTabSetRef, setTab, defaultLandingTab, loadCharacter, uiLanguage, selectedVrmIndex, walletConfig, elizaCloudConnected, setActionNotice, retryStartup, setWalletEnabled, forceLocalBootstrapRef, addDeferredOnboardingTask, client, } = deps;
+    // Destructure state fields we need from the onboarding hook
+    const { state: { step: onboardingStep, mode: onboardingMode, options: onboardingOptions, name: onboardingName, style: onboardingStyle, serverTarget: onboardingServerTarget, cloudApiKey: onboardingCloudApiKey, provider: onboardingProvider, apiKey: onboardingApiKey, voiceProvider: onboardingVoiceProvider, voiceApiKey: onboardingVoiceApiKey, smallModel: onboardingSmallModel, largeModel: onboardingLargeModel, openRouterModel: onboardingOpenRouterModel, primaryModel: onboardingPrimaryModel, detectedProviders: onboardingDetectedProviders, remoteApiBase: onboardingRemoteApiBase, remoteToken: onboardingRemoteToken, remote: onboardingRemote, rpcSelections: onboardingRpcSelections, rpcKeys: onboardingRpcKeys, featureTelegram: onboardingFeatureTelegram, featureDiscord: onboardingFeatureDiscord, featurePhone: onboardingFeaturePhone, featureCrypto: onboardingFeatureCrypto, featureBrowser: onboardingFeatureBrowser, featureComputerUse: onboardingFeatureComputerUse, cloudProvisionedContainer, }, completionCommittedRef: onboardingCompletionCommittedRef, } = onboarding;
+    const onboardingRemoteConnecting = onboardingRemote.status === "connecting";
+    // ── completeOnboarding ────────────────────────────────────────────
+    const completeOnboarding = useCallback((landingTab = defaultLandingTab, options) => {
+        clearPersistedOnboardingStep();
+        onboardingCompletionCommittedRef.current = true;
+        _setOnboardingMode("basic");
+        setOnboardingActiveGuide(null);
+        setPostOnboardingChecklistDismissed(false);
+        setOnboardingDetectedProviders(onboardingDetectedProviders.map((provider) => {
+            const { apiKey: _, ...rest } = provider;
+            return rest;
+        }));
+        setOnboardingComplete(true);
+        coordinatorOnboardingCompleteRef.current?.();
+        initialTabSetRef.current = true;
+        const launchCompanionOverlay = options?.launchCompanionOverlay === true &&
+            COMPANION_ENABLED &&
+            APPS_ENABLED;
+        if (launchCompanionOverlay) {
+            setActiveOverlayApp("@elizaos/app-companion");
+            replaceNavigationPathForCompanionLaunch();
+            setTab("apps");
+        }
+        else {
+            setTab(landingTab);
+        }
+        void loadCharacter();
+    }, [
+        onboardingCompletionCommittedRef,
+        onboardingDetectedProviders,
+        setOnboardingActiveGuide,
+        setOnboardingComplete,
+        setOnboardingDetectedProviders,
+        _setOnboardingMode,
+        setPostOnboardingChecklistDismissed,
+        setActiveOverlayApp,
+        setTab,
+        defaultLandingTab,
+        loadCharacter,
+        coordinatorOnboardingCompleteRef,
+        initialTabSetRef,
+    ]);
+    // ── runOnboardingChatHandoff ──────────────────────────────────────
+    const runOnboardingChatHandoff = useCallback(async (options) => {
+        if (!onboardingOptions)
+            return;
+        try {
+            const onboardingRunMode = onboardingMode === "elizacloudonly"
+                ? "cloud"
+                : onboardingMode === "basic" || onboardingMode === "advanced"
+                    ? "local"
+                    : "";
+            const useCloudFastTrack = shouldUseCloudOnboardingFastTrack({
+                cloudProvisionedContainer,
+                elizaCloudConnected,
+                onboardingRunMode,
+                onboardingProvider,
+            });
+            const onboardingFeaturePayload = buildOnboardingFeatureSubmitPayload({
+                onboardingFeatureTelegram,
+                onboardingFeatureDiscord,
+                onboardingFeatureBrowser,
+                onboardingFeatureComputerUse,
+            });
+            const shouldApplyLocalCapabilities = onboardingStep === "features";
+            const applySelectedLocalCapabilities = () => {
+                if (!shouldApplyLocalCapabilities)
+                    return;
+                setWalletEnabled?.(onboardingFeatureCrypto);
+                setBrowserEnabled?.(onboardingFeatureBrowser);
+                setComputerUseEnabled?.(onboardingFeatureComputerUse);
+            };
+            const runtimeConfig = buildOnboardingRuntimeConfig({
+                onboardingServerTarget,
+                onboardingCloudApiKey,
+                onboardingProvider,
+                onboardingApiKey,
+                omitRuntimeProvider: options?.omitRuntimeProvider,
+                onboardingVoiceProvider,
+                onboardingVoiceApiKey,
+                onboardingPrimaryModel,
+                onboardingOpenRouterModel,
+                onboardingRemoteConnected: onboardingRemote.status === "connected",
+                onboardingRemoteApiBase,
+                onboardingRemoteToken,
+                onboardingSmallModel,
+                onboardingLargeModel,
+                onboardingFeatureTelegram,
+                onboardingFeatureDiscord,
+                onboardingFeaturePhone,
+                onboardingFeatureCrypto,
+                onboardingFeatureBrowser,
+            });
+            const rpcSel = onboardingRpcSelections;
+            const rpcK = onboardingRpcKeys;
+            const nextWalletConfig = buildWalletRpcUpdateRequest({
+                walletConfig,
+                rpcFieldValues: rpcK,
+                selectedProviders: {
+                    evm: rpcSel.evm,
+                    bsc: rpcSel.bsc,
+                    solana: rpcSel.solana,
+                },
+            });
+            if (useCloudFastTrack) {
+                const style = resolveSelectedOnboardingStyle({
+                    styles: onboardingOptions.styles,
+                    onboardingStyle,
+                    selectedVrmIndex,
+                    uiLanguage,
+                });
+                const defaultName = style.name ?? getDefaultStylePreset(uiLanguage).name;
+                const fastTrackSandboxMode = isElizaCloudOnboardingTarget(onboardingServerTarget)
+                    ? "standard"
+                    : "off";
+                await client.submitOnboarding({
+                    name: onboardingName || defaultName,
+                    sandboxMode: fastTrackSandboxMode,
+                    bio: style?.bio ?? ["An autonomous AI agent."],
+                    systemPrompt: style?.system?.replace(/\{\{name\}\}/g, onboardingName || defaultName) ??
+                        `You are ${onboardingName || defaultName}, an autonomous AI agent powered by elizaOS.`,
+                    style: style?.style,
+                    adjectives: style?.adjectives,
+                    postExamples: style?.postExamples,
+                    messageExamples: style?.messageExamples,
+                    topics: style?.topics,
+                    avatarIndex: style?.avatarIndex ?? 1,
+                    language: uiLanguage,
+                    presetId: style?.id ?? getDefaultStylePreset(uiLanguage).id,
+                    deploymentTarget: runtimeConfig.deploymentTarget,
+                    ...(runtimeConfig.linkedAccounts
+                        ? { linkedAccounts: runtimeConfig.linkedAccounts }
+                        : {}),
+                    ...(runtimeConfig.serviceRouting
+                        ? { serviceRouting: runtimeConfig.serviceRouting }
+                        : {}),
+                    ...(runtimeConfig.credentialInputs
+                        ? { credentialInputs: runtimeConfig.credentialInputs }
+                        : {}),
+                    ...onboardingFeaturePayload,
+                    walletConfig: nextWalletConfig,
+                });
+                try {
+                    await persistOnboardingStyleVoice({
+                        style,
+                        voiceProvider: onboardingVoiceProvider,
+                        voiceApiKey: onboardingVoiceApiKey,
+                        cloudTtsSelected: runtimeConfig.serviceRouting?.tts?.transport ===
+                            "cloud-proxy" &&
+                            runtimeConfig.serviceRouting?.tts?.backend === "elizacloud",
+                        clientRef: client,
+                    });
+                }
+                catch (err) {
+                    console.warn("[onboarding] Failed to persist cloud voice preset", err);
+                }
+                applySelectedLocalCapabilities();
+                if (runtimeConfig.needsProviderSetup) {
+                    setActionNotice("Choose a chat provider in Settings to start chatting.", "info", 6000);
+                    completeOnboarding("settings");
+                    return;
+                }
+                await ensureOnboardedAgentRunning(client);
+                completeOnboarding("chat", { launchCompanionOverlay: true });
+                return;
+            }
+            const style = resolveSelectedOnboardingStyle({
+                styles: onboardingOptions.styles,
+                onboardingStyle,
+                selectedVrmIndex,
+                uiLanguage,
+            });
+            const systemPrompt = style?.system
+                ? style.system.replace(/\{\{name\}\}/g, onboardingName)
+                : `You are ${onboardingName}, an autonomous AI agent powered by elizaOS. ${onboardingOptions.sharedStyleRules}`;
+            const isSandboxMode = isElizaCloudOnboardingTarget(onboardingServerTarget);
+            const isLocalMode = onboardingServerTarget === "local" || !onboardingServerTarget;
+            const isRemoteMode = onboardingServerTarget === "remote";
+            if (isSandboxMode) {
+                const cloudApiBase = client.getBaseUrl().trim() ||
+                    getBootConfig().cloudApiBase ||
+                    "https://www.elizacloud.ai";
+                const authToken = String(globalThis
+                    .__ELIZA_CLOUD_AUTH_TOKEN__ ?? "");
+                if (!authToken) {
+                    throw new Error("Eliza Cloud authentication required. Please log in first.");
+                }
+                const provisionedAgent = await client.provisionCloudSandbox({
+                    cloudApiBase,
+                    authToken,
+                    name: onboardingName,
+                    bio: style?.bio ?? ["An autonomous AI agent."],
+                    onProgress: (status, detail) => {
+                        console.log(`[Sandbox] ${status}: ${detail ?? ""}`);
+                    },
+                });
+                client.setBaseUrl(provisionedAgent.bridgeUrl);
+                client.setToken(authToken);
+                persistMobileRuntimeModeForServerTarget(onboardingServerTarget);
+                savePersistedActiveServer(createPersistedActiveServer({
+                    kind: "cloud",
+                    apiBase: provisionedAgent.bridgeUrl,
+                    accessToken: authToken,
+                }));
+            }
+            else if (isLocalMode) {
+                const desktopRuntimeMode = await getDesktopRuntimeMode().catch(() => null);
+                const shouldStartEmbeddedDesktopRuntime = !desktopRuntimeMode || desktopRuntimeMode.mode === "local";
+                if (shouldStartEmbeddedDesktopRuntime) {
+                    try {
+                        await invokeDesktopBridgeRequest({
+                            rpcMethod: "agentStart",
+                            ipcChannel: "agent:start",
+                        });
+                    }
+                    catch {
+                        try {
+                            await startNativeAgentIfAvailable();
+                        }
+                        catch {
+                            /* dev mode where agent is already running */
+                        }
+                    }
+                }
+                const localDeadline = Date.now() + 120_000;
+                let pollMs = 1000;
+                while (Date.now() < localDeadline) {
+                    try {
+                        await client.getAuthStatus();
+                        break;
+                    }
+                    catch {
+                        await new Promise((r) => setTimeout(r, pollMs));
+                        pollMs = Math.min(pollMs * 1.5, 5000);
+                    }
+                }
+                savePersistedActiveServer(createPersistedActiveServer({ kind: "local" }));
+            }
+            else if (isRemoteMode) {
+                savePersistedActiveServer(createPersistedActiveServer({
+                    kind: "remote",
+                    apiBase: onboardingRemoteApiBase,
+                    accessToken: onboardingRemoteToken || undefined,
+                }));
+            }
+            const sandboxMode = isSandboxMode ? "standard" : "off";
+            await client.submitOnboarding({
+                name: onboardingName,
+                sandboxMode: sandboxMode,
+                bio: style?.bio ?? ["An autonomous AI agent."],
+                systemPrompt,
+                style: style?.style,
+                adjectives: style?.adjectives,
+                topics: style?.topics,
+                postExamples: style?.postExamples,
+                messageExamples: style?.messageExamples,
+                avatarIndex: style?.avatarIndex ?? selectedVrmIndex,
+                language: uiLanguage,
+                presetId: (style?.id ?? onboardingStyle) ||
+                    getDefaultStylePreset(uiLanguage).id,
+                deploymentTarget: runtimeConfig.deploymentTarget,
+                ...(runtimeConfig.linkedAccounts
+                    ? { linkedAccounts: runtimeConfig.linkedAccounts }
+                    : {}),
+                ...(runtimeConfig.serviceRouting
+                    ? { serviceRouting: runtimeConfig.serviceRouting }
+                    : {}),
+                ...(runtimeConfig.credentialInputs
+                    ? { credentialInputs: runtimeConfig.credentialInputs }
+                    : {}),
+                ...onboardingFeaturePayload,
+                walletConfig: nextWalletConfig,
+            });
+            try {
+                await persistOnboardingStyleVoice({
+                    style,
+                    voiceProvider: onboardingVoiceProvider,
+                    voiceApiKey: onboardingVoiceApiKey,
+                    cloudTtsSelected: runtimeConfig.serviceRouting?.tts?.transport === "cloud-proxy" &&
+                        runtimeConfig.serviceRouting?.tts?.backend === "elizacloud",
+                    clientRef: client,
+                });
+            }
+            catch (err) {
+                console.warn("[onboarding] Failed to persist selected voice preset", err);
+            }
+            applySelectedLocalCapabilities();
+            if (runtimeConfig.needsProviderSetup) {
+                setActionNotice("Choose a chat provider in Settings to start chatting.", "info", 6000);
+                completeOnboarding("settings");
+                return;
+            }
+            await ensureOnboardedAgentRunning(client);
+            completeOnboarding("chat", { launchCompanionOverlay: true });
+        }
+        catch (err) {
+            console.error("[onboarding] Failed to complete onboarding", err);
+            const message = err instanceof Error && err.message.trim()
+                ? `Failed to complete onboarding: ${err.message}`
+                : "Failed to complete onboarding.";
+            setActionNotice(message, "error", 8000);
+        }
+    }, [
+        onboardingOptions,
+        onboardingStyle,
+        onboardingName,
+        onboardingServerTarget,
+        onboardingCloudApiKey,
+        onboardingSmallModel,
+        onboardingLargeModel,
+        onboardingStep,
+        onboardingProvider,
+        onboardingApiKey,
+        onboardingRemoteApiBase,
+        onboardingRemote,
+        onboardingRemoteToken,
+        onboardingOpenRouterModel,
+        onboardingPrimaryModel,
+        onboardingFeatureTelegram,
+        onboardingFeatureDiscord,
+        onboardingFeaturePhone,
+        onboardingFeatureCrypto,
+        onboardingFeatureBrowser,
+        onboardingFeatureComputerUse,
+        onboardingVoiceProvider,
+        onboardingVoiceApiKey,
+        selectedVrmIndex,
+        uiLanguage,
+        onboardingRpcSelections,
+        onboardingRpcKeys,
+        setBrowserEnabled,
+        setComputerUseEnabled,
+        walletConfig,
+        onboardingMode,
+        elizaCloudConnected,
+        cloudProvisionedContainer,
+        completeOnboarding,
+        client,
+        setActionNotice,
+        setWalletEnabled,
+    ]);
+    // ── handleOnboardingFinish ────────────────────────────────────────
+    const handleOnboardingFinish = useCallback(async (options) => {
+        await runOnboardingChatHandoff(options);
+    }, [runOnboardingChatHandoff]);
+    // ── goToOnboardingStep ───────────────────────────────────────────
+    const goToOnboardingStep = useCallback((step) => {
+        setOnboardingStep(step);
+        setOnboardingActiveGuide(onboardingMode === "advanced"
+            ? getFlaminaTopicForOnboardingStep(step)
+            : null);
+    }, [onboardingMode, setOnboardingStep, setOnboardingActiveGuide]);
+    // ── applyResetConnectionWizardToHostingStep ───────────────────────
+    // Clears any residual onboarding selection state. The old wizard used
+    // this when jumping back to the "hosting" step so a stale remote/
+    // provider screen wouldn't bleed through. RuntimeGate doesn't jump
+    // between steps, but this still runs on revert paths.
+    const applyResetConnectionWizardToHostingStep = useCallback(() => {
+        const patch = {
+            onboardingServerTarget: "",
+            onboardingCloudApiKey: "",
+            onboardingApiKey: "",
+            onboardingPrimaryModel: "",
+            onboardingProvider: "",
+            onboardingRemoteApiBase: "",
+            onboardingRemoteToken: "",
+            onboardingRemoteConnected: false,
+            onboardingRemoteError: null,
+            onboardingRemoteConnecting: false,
+        };
+        if (patch.onboardingServerTarget !== undefined) {
+            persistMobileRuntimeModeForServerTarget(patch.onboardingServerTarget);
+            setOnboardingServerTarget(patch.onboardingServerTarget);
+        }
+        if (patch.onboardingCloudApiKey !== undefined) {
+            setOnboardingCloudApiKey(patch.onboardingCloudApiKey);
+        }
+        if (patch.onboardingProvider !== undefined) {
+            setOnboardingProvider(patch.onboardingProvider);
+        }
+        if (patch.onboardingApiKey !== undefined) {
+            setOnboardingApiKey(patch.onboardingApiKey);
+        }
+        if (patch.onboardingPrimaryModel !== undefined) {
+            _setOnboardingPrimaryModel(patch.onboardingPrimaryModel);
+        }
+        if (patch.onboardingRemoteApiBase !== undefined) {
+            setOnboardingRemoteApiBase(patch.onboardingRemoteApiBase);
+        }
+        if (patch.onboardingRemoteToken !== undefined) {
+            setOnboardingRemoteToken(patch.onboardingRemoteToken);
+        }
+        if (patch.onboardingRemoteError !== undefined) {
+            setOnboardingRemoteError(patch.onboardingRemoteError);
+        }
+        if (patch.onboardingRemoteConnecting !== undefined) {
+            setOnboardingRemoteConnecting(patch.onboardingRemoteConnecting);
+        }
+        if (patch.onboardingRemoteConnected !== undefined) {
+            setOnboardingRemoteConnected(patch.onboardingRemoteConnected);
+        }
+    }, [
+        setOnboardingApiKey,
+        setOnboardingCloudApiKey,
+        setOnboardingServerTarget,
+        _setOnboardingPrimaryModel,
+        setOnboardingProvider,
+        setOnboardingRemoteApiBase,
+        setOnboardingRemoteConnecting,
+        setOnboardingRemoteConnected,
+        setOnboardingRemoteError,
+        setOnboardingRemoteToken,
+    ]);
+    // ── advanceOnboarding / handleOnboardingNext ─────────────────────
+    const advanceOnboarding = useCallback(async (options) => {
+        if (shouldSkipConnectionStepsForCloudProvisionedContainer({
+            currentStep: onboardingStep,
+            cloudProvisionedContainer,
+        })) {
+            await handleOnboardingFinish(options);
+            return;
+        }
+        if (onboardingStep === "providers" && options?.allowPermissionBypass) {
+            if (options.skipTask)
+                addDeferredOnboardingTask(options.skipTask);
+        }
+        const nextStep = resolveOnboardingNextStep(onboardingStep);
+        // Keep any target-specific feature-step shortcuts centralized in flow.ts.
+        if (nextStep === "features" &&
+            shouldSkipFeaturesStep({ onboardingServerTarget })) {
+            await handleOnboardingFinish(options);
+            return;
+        }
+        if (!nextStep) {
+            // Last step (features) — finish onboarding and go to chat
+            await handleOnboardingFinish(options);
+            return;
+        }
+        if (nextStep) {
+            setOnboardingStep(nextStep);
+            setOnboardingActiveGuide(onboardingMode === "advanced"
+                ? getFlaminaTopicForOnboardingStep(nextStep)
+                : null);
+        }
+    }, [
+        handleOnboardingFinish,
+        onboardingMode,
+        onboardingStep,
+        onboardingServerTarget,
+        setOnboardingStep,
+        setOnboardingActiveGuide,
+        cloudProvisionedContainer,
+        addDeferredOnboardingTask,
+    ]);
+    const handleOnboardingNext = useCallback(async (options) => advanceOnboarding(options), [advanceOnboarding]);
+    // ── revertOnboarding / handleOnboardingBack ──────────────────────
+    const revertOnboarding = useCallback(() => {
+        const previousStep = resolveOnboardingPreviousStep(onboardingStep);
+        if (!previousStep)
+            return;
+        // Reset connection subflow when leaving "providers" so the user starts
+        // fresh at the hosting screen when they advance again.
+        if (onboardingStep === "providers") {
+            applyResetConnectionWizardToHostingStep();
+        }
+        setOnboardingStep(previousStep);
+        setOnboardingActiveGuide(onboardingMode === "advanced"
+            ? getFlaminaTopicForOnboardingStep(previousStep)
+            : null);
+    }, [
+        applyResetConnectionWizardToHostingStep,
+        onboardingMode,
+        onboardingStep,
+        setOnboardingActiveGuide,
+        setOnboardingStep,
+    ]);
+    const handleOnboardingBack = revertOnboarding;
+    // ── handleOnboardingJumpToStep ───────────────────────────────────
+    const handleOnboardingJumpToStep = useCallback((target) => {
+        if (!canRevertOnboardingTo({ current: onboardingStep, target }))
+            return;
+        const currentStepIndex = getOnboardingStepIndex(onboardingStep);
+        const targetStepIndex = getOnboardingStepIndex(target);
+        const providersStepIndex = getOnboardingStepIndex("providers");
+        // Sidebar back jumps must match repeated Back semantics, including the
+        // connection wizard reset when the jump crosses back past providers.
+        if (currentStepIndex >= providersStepIndex &&
+            targetStepIndex < providersStepIndex) {
+            applyResetConnectionWizardToHostingStep();
+        }
+        if (target === "deployment") {
+            persistMobileRuntimeModeForServerTarget("");
+            setOnboardingServerTarget("");
+        }
+        setOnboardingStep(target);
+        setOnboardingActiveGuide(onboardingMode === "advanced"
+            ? getFlaminaTopicForOnboardingStep(target)
+            : null);
+    }, [
+        applyResetConnectionWizardToHostingStep,
+        onboardingMode,
+        onboardingStep,
+        setOnboardingStep,
+        setOnboardingActiveGuide,
+        setOnboardingServerTarget,
+    ]);
+    // ── handleOnboardingUseLocalBackend ──────────────────────────────
+    const handleOnboardingUseLocalBackend = useCallback(() => {
+        forceLocalBootstrapRef.current = true;
+        clearPersistedActiveServer();
+        client.setBaseUrl(null);
+        client.setToken(null);
+        setOnboardingRemoteConnecting(false);
+        setOnboardingRemoteError(null);
+        setOnboardingRemoteConnected(false);
+        setOnboardingRemoteApiBase("");
+        setOnboardingRemoteToken("");
+        persistMobileRuntimeModeForServerTarget("");
+        setOnboardingServerTarget("");
+        setActionNotice("Checking this device for an existing Eliza setup...", "info", 3200);
+        retryStartup();
+    }, [
+        retryStartup,
+        setActionNotice,
+        forceLocalBootstrapRef,
+        setOnboardingRemoteApiBase,
+        setOnboardingRemoteConnected,
+        setOnboardingRemoteConnecting,
+        setOnboardingRemoteError,
+        setOnboardingRemoteToken,
+        setOnboardingServerTarget,
+        client,
+    ]);
+    // ── handleOnboardingRemoteConnect ────────────────────────────────
+    const handleOnboardingRemoteConnect = useCallback(async () => {
+        if (onboardingRemoteConnecting)
+            return;
+        let normalizedBase = "";
+        try {
+            normalizedBase = normalizeRemoteApiBaseInput(onboardingRemoteApiBase);
+        }
+        catch (err) {
+            setOnboardingRemoteError(err instanceof Error ? err.message : "Enter a valid backend address.");
+            return;
+        }
+        const accessKey = onboardingRemoteToken.trim();
+        const probe = new ElizaClient(normalizedBase, accessKey || undefined);
+        setOnboardingRemoteConnecting(true);
+        setOnboardingRemoteError(null);
+        try {
+            const auth = await probe.getAuthStatus();
+            if (auth.required && !accessKey) {
+                throw new Error("This backend requires an access key.");
+            }
+            await probe.getOnboardingStatus();
+            savePersistedActiveServer(createPersistedActiveServer({
+                kind: "remote",
+                apiBase: normalizedBase,
+                ...(accessKey ? { accessToken: accessKey } : {}),
+            }));
+            persistMobileRuntimeModeForServerTarget("remote");
+            setOnboardingServerTarget("remote");
+            setOnboardingRemoteApiBase(normalizedBase);
+            setOnboardingRemoteToken(accessKey);
+            setOnboardingRemoteConnected(true);
+            setActionNotice("Connected to remote backend.", "success", 4200);
+            retryStartup();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Failed to reach remote backend.";
+            const normalizedMessage = /401|unauthorized|forbidden/i.test(message) && accessKey
+                ? "Access key rejected. Check the address and try again."
+                : message;
+            setOnboardingRemoteError(normalizedMessage);
+        }
+        finally {
+            setOnboardingRemoteConnecting(false);
+        }
+    }, [
+        onboardingRemoteApiBase,
+        onboardingRemoteConnecting,
+        onboardingRemoteToken,
+        retryStartup,
+        setActionNotice,
+        setOnboardingRemoteApiBase,
+        setOnboardingRemoteConnected,
+        setOnboardingRemoteConnecting,
+        setOnboardingRemoteError,
+        setOnboardingRemoteToken,
+        setOnboardingServerTarget,
+    ]);
+    // ── handleCloudOnboardingFinish ──────────────────────────────────
+    const handleCloudOnboardingFinish = useCallback(async () => {
+        await runOnboardingChatHandoff();
+    }, [runOnboardingChatHandoff]);
+    // ── applyDetectedProviders ───────────────────────────────────────
+    const applyDetectedProviders = useCallback((detected) => {
+        setOnboardingDetectedProviders(detected);
+    }, [setOnboardingDetectedProviders]);
+    return {
+        completeOnboarding,
+        runOnboardingChatHandoff,
+        handleOnboardingFinish,
+        goToOnboardingStep,
+        applyResetConnectionWizardToHostingStep,
+        advanceOnboarding,
+        handleOnboardingNext,
+        revertOnboarding,
+        handleOnboardingBack,
+        handleOnboardingJumpToStep,
+        handleOnboardingUseLocalBackend,
+        handleOnboardingRemoteConnect,
+        handleCloudOnboardingFinish,
+        applyDetectedProviders,
+    };
+}