@elizaos/ui 2.0.0-beta.2 → 2.0.3-beta.3

package/state/useFirstRunState.d.ts

@@ -0,0 +1,126 @@
+/**
+ * First-run state — consolidated via useReducer.
+ *
+ * Replaces 35+ individual useState hooks with structured reducers.
+ * Connector tokens (telegram, discord, etc.) collapse into a single Record.
+ * Remote connection state (connecting/connected/error) collapses into one object.
+ */
+import type { FirstRunOptions } from "../api/index.js";
+import { type FirstRunRuntimeTarget } from "../first-run/runtime-target.js";
+import type { AppState, SetupStep } from "./types.js";
+export type ConnectorTokenKey = "telegramToken" | "discordToken" | "whatsAppSessionPath" | "twilioAccountSid" | "twilioAuthToken" | "twilioPhoneNumber" | "blooioApiKey" | "blooioPhoneNumber" | "githubToken";
+export interface RemoteConnectionState {
+    status: "idle" | "connecting" | "connected" | "error";
+    error: string | null;
+}
+export interface FirstRunState {
+    step: SetupStep;
+    mode: AppState["firstRunMode"];
+    activeGuide: string | null;
+    deferredTasks: string[];
+    postChecklistDismissed: boolean;
+    options: FirstRunOptions | null;
+    name: string;
+    ownerName: string;
+    style: string;
+    avatar: number;
+    serverTarget: FirstRunRuntimeTarget;
+    cloudApiKey: string;
+    provider: string;
+    apiKey: string;
+    voiceProvider: string;
+    voiceApiKey: string;
+    nanoModel: string;
+    smallModel: string;
+    mediumModel: string;
+    largeModel: string;
+    megaModel: string;
+    openRouterModel: string;
+    primaryModel: string;
+    existingInstallDetected: boolean;
+    detectedProviders: AppState["firstRunDetectedProviders"];
+    connectorTokens: Record<ConnectorTokenKey, string>;
+    remote: RemoteConnectionState;
+    remoteApiBase: string;
+    remoteToken: string;
+    subscriptionTab: "token" | "oauth";
+    elizaCloudTab: "login" | "apikey";
+    selectedChains: Set<string>;
+    rpcSelections: Record<string, string>;
+    rpcKeys: Record<string, string>;
+    featureTelegram: boolean;
+    featureDiscord: boolean;
+    featurePhone: boolean;
+    featureCrypto: boolean;
+    featureBrowser: boolean;
+    featureComputerUse: boolean;
+    featureOAuthPending: string | null;
+    restarting: boolean;
+    cloudProvisionedContainer: boolean;
+}
+type FirstRunAction = {
+    type: "SET_STEP";
+    step: SetupStep;
+} | {
+    type: "SET_MODE";
+    mode: AppState["firstRunMode"];
+} | {
+    type: "SET_ACTIVE_GUIDE";
+    guide: string | null;
+} | {
+    type: "ADD_DEFERRED_TASK";
+    task: string;
+} | {
+    type: "SET_DEFERRED_TASKS";
+    tasks: string[];
+} | {
+    type: "SET_POST_CHECKLIST_DISMISSED";
+    value: boolean;
+} | {
+    type: "SET_OPTIONS";
+    options: FirstRunOptions | null;
+} | {
+    type: "SET_FIELD";
+    field: string;
+    value: unknown;
+} | {
+    type: "SET_CONNECTOR_TOKEN";
+    key: ConnectorTokenKey;
+    value: string;
+} | {
+    type: "SET_REMOTE_STATUS";
+    status: RemoteConnectionState["status"];
+    error?: string | null;
+} | {
+    type: "SET_REMOTE_API_BASE";
+    value: string;
+} | {
+    type: "SET_REMOTE_TOKEN";
+    value: string;
+} | {
+    type: "SET_DETECTED_PROVIDERS";
+    value: AppState["firstRunDetectedProviders"];
+} | {
+    type: "RESET_FOR_NEW_FIRST_RUN";
+};
+export interface FirstRunStateHook {
+    state: FirstRunState;
+    dispatch: React.Dispatch<FirstRunAction>;
+    setStep: (step: SetupStep) => void;
+    setMode: (mode: AppState["firstRunMode"]) => void;
+    setActiveGuide: (guide: string | null) => void;
+    addDeferredTask: (task: string) => void;
+    setDeferredTasks: (tasks: string[]) => void;
+    setOptions: (options: FirstRunOptions | null) => void;
+    setField: (field: string, value: unknown) => void;
+    setConnectorToken: (key: ConnectorTokenKey, value: string) => void;
+    setRemoteStatus: (status: RemoteConnectionState["status"], error?: string | null) => void;
+    setDetectedProviders: (value: AppState["firstRunDetectedProviders"]) => void;
+    /** Tracks whether first-run completion has been committed this session. */
+    completionCommittedRef: React.RefObject<boolean>;
+    /** Force local bootstrap ref. */
+    forceLocalBootstrapRef: React.RefObject<boolean>;
+}
+export declare function useFirstRunState(cloudOnly?: boolean): FirstRunStateHook;
+export type { FirstRunAction as FirstRunDispatchAction };
+//# sourceMappingURL=useFirstRunState.d.ts.map

package/state/useFirstRunState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFirstRunState.d.ts","sourceRoot":"","sources":["../../../../../src/state/useFirstRunState.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6BAA6B,CAAC;AAOrC,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAInD,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,cAAc,GACd,qBAAqB,GACrB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,cAAc,GACd,mBAAmB,GACnB,aAAa,CAAC;AAIlB,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;IACtD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sBAAsB,EAAE,OAAO,CAAC;IAChC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAGhC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IAGf,YAAY,EAAE,qBAAqB,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IAGpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,OAAO,CAAC;IACjC,iBAAiB,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAAC;IAGzD,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAGnD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IAGpB,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,aAAa,EAAE,OAAO,GAAG,QAAQ,CAAC;IAGlC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGhC,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAGnC,UAAU,EAAE,OAAO,CAAC;IACpB,yBAAyB,EAAE,OAAO,CAAC;CACpC;AA2JD,KAAK,cAAc,GACf;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtE;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3C;IACE,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAAC;CAC9C,GACD;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAmExC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEzC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAClD,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5C,UAAU,EAAE,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,KAAK,IAAI,CAAC;IACtD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,iBAAiB,EAAE,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,eAAe,EAAE,CACf,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACvC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,KAClB,IAAI,CAAC;IACV,oBAAoB,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,2BAA2B,CAAC,KAAK,IAAI,CAAC;IAE7E,2EAA2E;IAC3E,sBAAsB,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjD,iCAAiC;IACjC,sBAAsB,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CAClD;AAED,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,iBAAiB,CA0EvE;AAED,YAAY,EAAE,cAAc,IAAI,sBAAsB,EAAE,CAAC"}

package/state/useFirstRunState.js

@@ -0,0 +1,259 @@
+/**
+ * First-run state — consolidated via useReducer.
+ *
+ * Replaces 35+ individual useState hooks with structured reducers.
+ * Connector tokens (telegram, discord, etc.) collapse into a single Record.
+ * Remote connection state (connecting/connected/error) collapses into one object.
+ */
+import { DEFAULT_ELIZA_CLOUD_TEXT_MODEL, getDefaultStylePreset, } from "@elizaos/shared";
+import { useCallback, useReducer, useRef } from "react";
+import { readPersistedMobileRuntimeMode } from "../first-run/mobile-runtime-mode.js";
+import { activeServerKindToFirstRunRuntimeTarget, } from "../first-run/runtime-target.js";
+import { canRunLocal } from "../platform/init.js";
+import { loadPersistedActiveServer, loadPersistedSetupStep, saveSetupStep, } from "./persistence.js";
+function isRemoteApiBase(baseUrl) {
+    if (!baseUrl || typeof window === "undefined")
+        return false;
+    try {
+        const parsed = new URL(baseUrl);
+        return (parsed.hostname !== window.location.hostname &&
+            parsed.hostname !== "localhost" &&
+            parsed.hostname !== "127.0.0.1" &&
+            parsed.hostname !== "::1");
+    }
+    catch {
+        return false;
+    }
+}
+const EMPTY_TOKENS = {
+    telegramToken: "",
+    discordToken: "",
+    whatsAppSessionPath: "",
+    twilioAccountSid: "",
+    twilioAuthToken: "",
+    twilioPhoneNumber: "",
+    blooioApiKey: "",
+    blooioPhoneNumber: "",
+    githubToken: "",
+};
+function loadInitialServerSelection() {
+    const activeServer = loadPersistedActiveServer();
+    if (!activeServer) {
+        return {
+            serverTarget: "",
+            remote: {
+                status: "idle",
+                error: null,
+            },
+            remoteApiBase: "",
+            remoteToken: "",
+        };
+    }
+    if (activeServer.kind === "local") {
+        return {
+            serverTarget: activeServerKindToFirstRunRuntimeTarget(activeServer.kind),
+            remote: {
+                status: "idle",
+                error: null,
+            },
+            remoteApiBase: "",
+            remoteToken: "",
+        };
+    }
+    if (activeServer.kind === "cloud") {
+        const serverTarget = readPersistedMobileRuntimeMode() === "cloud-hybrid"
+            ? "elizacloud-hybrid"
+            : activeServerKindToFirstRunRuntimeTarget(activeServer.kind);
+        return {
+            serverTarget,
+            remote: {
+                status: "idle",
+                error: null,
+            },
+            remoteApiBase: "",
+            remoteToken: activeServer.accessToken?.trim() ?? "",
+        };
+    }
+    const apiBase = activeServer.apiBase?.trim() ?? "";
+    return {
+        serverTarget: activeServerKindToFirstRunRuntimeTarget(activeServer.kind),
+        remote: {
+            status: isRemoteApiBase(apiBase) ? "connected" : "idle",
+            error: null,
+        },
+        remoteApiBase: apiBase,
+        remoteToken: activeServer.accessToken?.trim() ?? "",
+    };
+}
+function createInitialState(cloudOnly) {
+    const defaultStyle = getDefaultStylePreset();
+    const initialServer = loadInitialServerSelection();
+    const initialServerTarget = cloudOnly
+        ? readPersistedMobileRuntimeMode() === "cloud-hybrid"
+            ? "elizacloud-hybrid"
+            : "elizacloud"
+        : initialServer.serverTarget;
+    const persistedStep = loadPersistedSetupStep();
+    const skipConnection = canRunLocal();
+    let step = persistedStep ?? (skipConnection ? "model" : "connection");
+    if (skipConnection && step === "connection") {
+        step = "model";
+    }
+    const serverTarget = initialServerTarget || (skipConnection && step === "model" ? "local" : "");
+    return {
+        step,
+        mode: "basic",
+        activeGuide: null,
+        deferredTasks: [],
+        postChecklistDismissed: false,
+        options: null,
+        name: defaultStyle.name,
+        ownerName: "anon",
+        style: defaultStyle.id,
+        avatar: defaultStyle.avatarIndex,
+        serverTarget,
+        cloudApiKey: "",
+        provider: "",
+        apiKey: "",
+        voiceProvider: "",
+        voiceApiKey: "",
+        nanoModel: DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+        smallModel: DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+        mediumModel: DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+        largeModel: DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+        megaModel: DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+        openRouterModel: "",
+        primaryModel: "",
+        existingInstallDetected: false,
+        detectedProviders: [],
+        connectorTokens: { ...EMPTY_TOKENS },
+        remote: initialServer.remote,
+        remoteApiBase: initialServer.remoteApiBase,
+        remoteToken: initialServer.remoteToken,
+        subscriptionTab: "token",
+        elizaCloudTab: "login",
+        selectedChains: new Set(["evm", "solana"]),
+        rpcSelections: {},
+        rpcKeys: {},
+        featureTelegram: false,
+        featureDiscord: false,
+        featurePhone: false,
+        featureCrypto: true,
+        featureBrowser: true,
+        featureComputerUse: false,
+        featureOAuthPending: null,
+        restarting: false,
+        cloudProvisionedContainer: false,
+    };
+}
+function firstRunReducer(state, action) {
+    switch (action.type) {
+        case "SET_STEP":
+            return { ...state, step: action.step };
+        case "SET_MODE":
+            return { ...state, mode: action.mode };
+        case "SET_ACTIVE_GUIDE":
+            return { ...state, activeGuide: action.guide };
+        case "ADD_DEFERRED_TASK":
+            if (state.deferredTasks.includes(action.task))
+                return state;
+            return {
+                ...state,
+                deferredTasks: [...state.deferredTasks, action.task],
+                postChecklistDismissed: false,
+            };
+        case "SET_DEFERRED_TASKS":
+            return {
+                ...state,
+                deferredTasks: [...new Set(action.tasks)],
+            };
+        case "SET_POST_CHECKLIST_DISMISSED":
+            return { ...state, postChecklistDismissed: action.value };
+        case "SET_OPTIONS":
+            return { ...state, options: action.options };
+        case "SET_FIELD": {
+            if (action.field === "serverTarget") {
+                return {
+                    ...state,
+                    serverTarget: action.value,
+                };
+            }
+            return { ...state, [action.field]: action.value };
+        }
+        case "SET_CONNECTOR_TOKEN":
+            return {
+                ...state,
+                connectorTokens: {
+                    ...state.connectorTokens,
+                    [action.key]: action.value,
+                },
+            };
+        case "SET_REMOTE_STATUS":
+            return {
+                ...state,
+                remote: { status: action.status, error: action.error ?? null },
+            };
+        case "SET_REMOTE_API_BASE":
+            return { ...state, remoteApiBase: action.value };
+        case "SET_REMOTE_TOKEN":
+            return { ...state, remoteToken: action.value };
+        case "SET_DETECTED_PROVIDERS":
+            return { ...state, detectedProviders: action.value };
+        case "RESET_FOR_NEW_FIRST_RUN":
+            return createInitialState();
+        default:
+            return state;
+    }
+}
+export function useFirstRunState(cloudOnly) {
+    const [state, dispatch] = useReducer(firstRunReducer, cloudOnly, (co) => createInitialState(co));
+    const completionCommittedRef = useRef(false);
+    const forceLocalBootstrapRef = useRef(false);
+    const setStep = useCallback((step) => {
+        dispatch({ type: "SET_STEP", step });
+        saveSetupStep(step);
+    }, []);
+    const setMode = useCallback((mode) => {
+        dispatch({ type: "SET_MODE", mode });
+    }, []);
+    const setActiveGuide = useCallback((guide) => {
+        dispatch({ type: "SET_ACTIVE_GUIDE", guide });
+    }, []);
+    const addDeferredTask = useCallback((task) => {
+        dispatch({ type: "ADD_DEFERRED_TASK", task });
+    }, []);
+    const setDeferredTasks = useCallback((tasks) => {
+        dispatch({ type: "SET_DEFERRED_TASKS", tasks });
+    }, []);
+    const setOptions = useCallback((options) => {
+        dispatch({ type: "SET_OPTIONS", options });
+    }, []);
+    const setField = useCallback((field, value) => {
+        dispatch({ type: "SET_FIELD", field, value });
+    }, []);
+    const setConnectorToken = useCallback((key, value) => {
+        dispatch({ type: "SET_CONNECTOR_TOKEN", key, value });
+    }, []);
+    const setRemoteStatus = useCallback((status, error) => {
+        dispatch({ type: "SET_REMOTE_STATUS", status, error });
+    }, []);
+    const setDetectedProviders = useCallback((value) => {
+        dispatch({ type: "SET_DETECTED_PROVIDERS", value });
+    }, []);
+    return {
+        state,
+        dispatch,
+        setStep,
+        setMode,
+        setActiveGuide,
+        addDeferredTask,
+        setDeferredTasks,
+        setOptions,
+        setField,
+        setConnectorToken,
+        setRemoteStatus,
+        setDetectedProviders,
+        completionCommittedRef,
+        forceLocalBootstrapRef,
+    };
+}

package/state/useLifecycleState.d.ts

@@ -4,14 +4,17 @@
  * Replaces 20+ individual useState hooks from AppContext with a single
  * reducer + dispatch, cutting hook count and making state transitions explicit.
  */
-import type { AgentStatus } from "../api";
-import type { ActionNotice, AppState, LifecycleAction, StartupErrorState, StartupPhase } from "./types";
+import type { AgentStatus } from "../api/index.js";
+import { type CloudHandoffPhaseDetail } from "../events/index.js";
+import type { ActionBanner, ActionNotice, AppState, LifecycleAction, StartupErrorState, StartupPhase } from "./types.js";
 export interface LifecycleState {
     connected: boolean;
     agentStatus: AgentStatus | null;
-    onboardingComplete: boolean;
-    onboardingUiRevealNonce: number;
-    onboardingLoading: boolean;
+    /** Latest shared→dedicated cloud-agent handoff phase (see CLOUD_HANDOFF_PHASE_EVENT). */
+    cloudHandoffPhase: CloudHandoffPhaseDetail | null;
+    firstRunComplete: boolean;
+    firstRunUiRevealNonce: number;
+    firstRunLoading: boolean;
     startupPhase: StartupPhase;
     startupError: StartupErrorState | null;
     startupRetryNonce: number;
@@ -25,6 +28,7 @@ export interface LifecycleState {
     backendConnection: AppState["backendConnection"];
     backendDisconnectedBannerDismissed: boolean;
     systemWarnings: string[];
+    actionBanner: ActionBanner | null;
 }
 type LifecycleAction_ = {
     type: "SET_CONNECTED";
@@ -33,12 +37,15 @@ type LifecycleAction_ = {
     type: "SET_AGENT_STATUS";
     value: AgentStatus | null;
 } | {
-    type: "SET_ONBOARDING_COMPLETE";
+    type: "SET_CLOUD_HANDOFF_PHASE";
+    value: CloudHandoffPhaseDetail | null;
+} | {
+    type: "SET_FIRST_RUN_COMPLETE";
     value: boolean;
 } | {
-    type: "INCREMENT_ONBOARDING_REVEAL_NONCE";
+    type: "INCREMENT_FIRST_RUN_REVEAL_NONCE";
 } | {
-    type: "SET_ONBOARDING_LOADING";
+    type: "SET_FIRST_RUN_LOADING";
     value: boolean;
 } | {
     type: "SET_STARTUP_PHASE";
@@ -83,6 +90,11 @@ type LifecycleAction_ = {
 } | {
     type: "SET_SYSTEM_WARNINGS";
     value: string[];
+} | {
+    type: "SET_ACTION_BANNER";
+    value: ActionBanner;
+} | {
+    type: "CLEAR_ACTION_BANNER";
 };
 export interface LifecycleStateHook {
     /** The consolidated lifecycle state. */
@@ -93,9 +105,10 @@ export interface LifecycleStateHook {
     setAgentStatus: (v: AgentStatus | null) => void;
     /** Only calls setAgentStatus when the payload has materially changed. */
     setAgentStatusIfChanged: (next: AgentStatus | null) => void;
-    setOnboardingComplete: (v: boolean) => void;
-    incrementOnboardingRevealNonce: () => void;
-    setOnboardingLoading: (v: boolean) => void;
+    setCloudHandoffPhase: (v: CloudHandoffPhaseDetail | null) => void;
+    setFirstRunComplete: (v: boolean) => void;
+    incrementFirstRunRevealNonce: () => void;
+    setFirstRunLoading: (v: boolean) => void;
     setStartupPhase: (v: StartupPhase) => void;
     setStartupError: (v: StartupErrorState | null) => void;
     retryStartup: () => void;
@@ -112,6 +125,8 @@ export interface LifecycleStateHook {
     addSystemWarning: (warning: string) => void;
     dismissSystemWarning: (message: string) => void;
     setSystemWarnings: (v: string[]) => void;
+    showActionBanner: (banner: ActionBanner) => void;
+    dismissActionBanner: () => void;
     /** Derived startup status. */
     startupStatus: AppState["startupStatus"];
     lifecycleBusyRef: React.RefObject<boolean>;

package/state/useLifecycleState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLifecycleState.d.ts","sourceRoot":"","sources":["../../../../../src/state/useLifecycleState.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useLifecycleState.d.ts","sourceRoot":"","sources":["../../../../../src/state/useLifecycleState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,YAAY,EACb,MAAM,SAAS,CAAC;AAIjB,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,yFAAyF;IACzF,iBAAiB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAClD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,sBAAsB,EAAE,OAAO,CAAC;IAChC,iBAAiB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACjD,kCAAkC,EAAE,OAAO,CAAC;IAC5C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AAgCD,KAAK,gBAAgB,GACjB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,kCAAkC,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,wBAAwB,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IACE,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC;CAC/C,GACD;IAAE,IAAI,EAAE,wBAAwB,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,0BAA0B,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,CAAC;AA4GpC,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,EAAE,cAAc,CAAC;IACtB,mDAAmD;IACnD,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAG3C,YAAY,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,yEAAyE;IACzE,uBAAuB,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5D,oBAAoB,EAAE,CAAC,CAAC,EAAE,uBAAuB,GAAG,IAAI,KAAK,IAAI,CAAC;IAClE,mBAAmB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,4BAA4B,EAAE,MAAM,IAAI,CAAC;IACzC,kBAAkB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,eAAe,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3C,eAAe,EAAE,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,KAAK,IAAI,CAAC;IACvD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,eAAe,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,eAAe,EAAE,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,EACnC,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,OAAO,KACX,IAAI,CAAC;IACV,oBAAoB,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC;IAC3D,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAClC,iBAAiB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAClE,oBAAoB,EAAE,MAAM,IAAI,CAAC;IACjC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,oBAAoB,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,KAAK,IAAI,CAAC;IAC1E,oBAAoB,EAAE,MAAM,IAAI,CAAC;IACjC,sBAAsB,EAAE,MAAM,IAAI,CAAC;IACnC,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,oBAAoB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,iBAAiB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACzC,gBAAgB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IACjD,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAEhC,8BAA8B;IAC9B,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAGzC,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC3C,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAC5D,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACrD;AAED,wBAAgB,iBAAiB,IAAI,kBAAkB,CA0PtD;AAED,YAAY,EAAE,gBAAgB,IAAI,uBAAuB,EAAE,CAAC"}