@elizaos/ui 2.0.0-beta.1 → 2.0.11-beta.7

package/state/useStartupCoordinator.js

@@ -0,0 +1,290 @@
+/**
+ * useStartupCoordinator — React hook that drives the StartupCoordinator
+ * state machine with side effects.
+ *
+ * This hook is the SOLE startup authority. It:
+ * 1. Uses useReducer with the coordinator's startupReducer
+ * 2. Delegates per-phase work to phase modules (startup-phase-*.ts)
+ * 3. Dispatches events as async operations complete
+ * 4. Syncs coordinator state to the legacy lifecycle setters
+ *
+ * Architecture: Each phase is handled by a dedicated function imported from
+ * a phase module. One-time hydration work runs in the "hydrating" effect.
+ * Persistent WS bindings and navigation listeners are set up via bindReadyPhase
+ * in a "ready" effect that only cleans up on unmount (not on phase transitions).
+ */
+import { logger } from "@elizaos/logger";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import { client } from "../api/index.js";
+import { isElectrobunRuntime } from "../bridge/index.js";
+import { isAndroid, isElizaOS, isIOS, isNative } from "../platform/index.js";
+import { createAndroidPolicy, createDesktopPolicy, createElizaOSPolicy, createIosPolicy, createMobilePolicy, createWebPolicy, INITIAL_STARTUP_STATE, isStartupLoading, isStartupTerminal, startupReducer, toLegacyStartupPhase, } from "./startup-coordinator.js";
+import { bindReadyPhase, runHydrating, } from "./startup-phase-hydrate.js";
+import { runPollingBackend, } from "./startup-phase-poll.js";
+import { runRestoringSession, } from "./startup-phase-restore.js";
+import { runStartingRuntime, } from "./startup-phase-runtime.js";
+// Auto-recovery backoff: probe the backend after a transient startup error,
+// backing off 2.5s → 5s → 10s → 20s → cap 30s, and give up after a bounded
+// number of attempts so a genuinely-down backend stops thrashing and the user
+// falls back to the manual Retry button.
+const RECOVERY_BASE_DELAY_MS = 2_500;
+const RECOVERY_MAX_DELAY_MS = 30_000;
+const RECOVERY_MAX_ATTEMPTS = 8;
+function isRecoverableStartupErrorReason(reason) {
+    return (reason === "backend-timeout" ||
+        reason === "backend-unreachable" ||
+        reason === "agent-timeout" ||
+        reason === "agent-error" ||
+        reason === "unknown");
+}
+export async function recoverTerminalStartupError(deps, dispatch, cancelled) {
+    let status;
+    try {
+        status = await client.getStatus();
+    }
+    catch {
+        return false;
+    }
+    if (cancelled.current || status.state !== "running")
+        return false;
+    let firstRunComplete = deps.firstRunCompletionCommittedRef.current;
+    try {
+        const firstRunStatus = await client.getFirstRunStatus();
+        firstRunComplete = firstRunComplete || firstRunStatus.complete === true;
+    }
+    catch {
+        return false;
+    }
+    if (cancelled.current)
+        return false;
+    deps.setAgentStatus(status);
+    deps.setConnected(true);
+    deps.setStartupError(null);
+    deps.setFirstRunLoading(false);
+    deps.setFirstRunComplete(firstRunComplete);
+    if (firstRunComplete) {
+        dispatch({ type: "AGENT_RUNNING" });
+    }
+    else {
+        dispatch({ type: "BACKEND_REACHED", firstRunComplete: false });
+    }
+    return true;
+}
+function detectPlatformPolicy() {
+    if (isElectrobunRuntime())
+        return createDesktopPolicy();
+    // ElizaOS check must come before the generic mobile branch — both are
+    // native, but ElizaOS bundles the on-device agent and needs the longer
+    // backend timeout (vanilla mobile is cloud-only with a fast-fail budget).
+    if (isElizaOS())
+        return createElizaOSPolicy();
+    if (isAndroid)
+        return createAndroidPolicy();
+    if (isIOS)
+        return createIosPolicy();
+    if (isNative)
+        return createMobilePolicy();
+    return createWebPolicy();
+}
+// ── Hook ────────────────────────────────────────────────────────────
+export function useStartupCoordinator(deps) {
+    const [state, dispatch] = useReducer(startupReducer, INITIAL_STARTUP_STATE);
+    const policy = useRef(detectPlatformPolicy()).current;
+    const effectRunRef = useRef(0);
+    // Deps ref — effects always access latest deps without re-triggering
+    const depsRef = useRef(deps);
+    depsRef.current = deps;
+    const depsReady = deps != null;
+    // Session context carried between restoring-session and polling-backend
+    const _ctx = useRef(null);
+    // Track whether the ready-phase WS bindings have been set up
+    const wsBindingsActiveRef = useRef(false);
+    // ── Legacy sync — derive startupPhase from coordinator state ────
+    const legacyPhase = toLegacyStartupPhase(state);
+    useEffect(() => {
+        if (!depsReady)
+            return;
+        depsRef.current?.setStartupPhase(legacyPhase);
+    }, [legacyPhase, depsReady]);
+    // ── Phase: restoring-session ────────────────────────────────────
+    useEffect(() => {
+        if (state.phase !== "restoring-session" || !depsReady)
+            return;
+        const d = depsRef.current;
+        if (!d)
+            return;
+        effectRunRef.current += 1;
+        const cancelled = { current: false };
+        runRestoringSession(d, dispatch, _ctx, cancelled).catch(() => { });
+        return () => {
+            cancelled.current = true;
+        };
+    }, [state.phase, depsReady]);
+    // ── Phase: resolving-target (auto-advance) ──────────────────────
+    useEffect(() => {
+        if (state.phase !== "resolving-target")
+            return;
+        dispatch({ type: "BACKEND_POLL_RETRY" });
+    }, [state.phase]);
+    // ── Phase: polling-backend ──────────────────────────────────────
+    useEffect(() => {
+        if (state.phase !== "polling-backend" || !depsReady)
+            return;
+        const currentDeps = depsRef.current;
+        if (!currentDeps)
+            return;
+        effectRunRef.current += 1;
+        const runId = effectRunRef.current;
+        const cancelled = { current: false };
+        const tidRef = { current: null };
+        runPollingBackend(currentDeps, dispatch, policy, _ctx.current, runId, effectRunRef, cancelled, tidRef).catch(() => { });
+        return () => {
+            cancelled.current = true;
+            if (tidRef.current)
+                clearTimeout(tidRef.current);
+        };
+    }, [state.phase, policy.backendTimeoutMs, depsReady, policy]);
+    // ── Phase: starting-runtime ─────────────────────────────────────
+    // The runtime target is fixed for a given starting-runtime entry (it is
+    // carried in the state object and never mutates in place), so re-running on
+    // `state.phase` alone already picks up the correct target. The local
+    // primitive keeps it readable inside the effect without widening the deps.
+    const startingRuntimeTarget = state.phase === "starting-runtime" ? state.target : null;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: startingRuntimeTarget is constant across a single starting-runtime entry; state.phase is the real trigger.
+    useEffect(() => {
+        if (state.phase !== "starting-runtime" || !depsReady)
+            return;
+        const currentDeps = depsRef.current;
+        if (!currentDeps || !startingRuntimeTarget)
+            return;
+        effectRunRef.current += 1;
+        const runId = effectRunRef.current;
+        const cancelled = { current: false };
+        const tidRef = { current: null };
+        runStartingRuntime(currentDeps, dispatch, runId, effectRunRef, cancelled, tidRef, startingRuntimeTarget).catch(() => { });
+        return () => {
+            cancelled.current = true;
+            if (tidRef.current)
+                clearTimeout(tidRef.current);
+        };
+    }, [state.phase, depsReady]);
+    // ── Phase: hydrating — one-time data load, then HYDRATION_COMPLETE ─
+    useEffect(() => {
+        if (state.phase !== "hydrating" || !depsReady)
+            return;
+        const currentDeps = depsRef.current;
+        if (!currentDeps)
+            return;
+        const cancelled = { current: false };
+        runHydrating(currentDeps, dispatch, cancelled).catch((err) => {
+            // Hydration decorates the shell (wallet, avatar, autonomy replay…);
+            // everything past conversation restore is best-effort. Completing with
+            // partial data beats stranding the composer in "connecting" forever —
+            // and the reducer no-ops HYDRATION_COMPLETE outside "hydrating", so
+            // this can only ever unlock a stalled boot, never mis-transition.
+            logger.warn(`[eliza][startup:init] hydration failed; completing with partial data: ${err instanceof Error ? err.message : String(err)}`);
+            dispatch({ type: "HYDRATION_COMPLETE" });
+        });
+        return () => {
+            cancelled.current = true;
+        };
+    }, [state.phase, depsReady]);
+    // ── Ready phase — persistent WS bindings + nav listener ─────────
+    // This effect runs once when the coordinator reaches "ready" and stays
+    // active until the component unmounts. It does NOT depend on state.phase
+    // after the guard, so phase transitions won't clean up WS bindings.
+    const readyPhaseReached = state.phase === "ready";
+    useEffect(() => {
+        if (!readyPhaseReached || !depsReady)
+            return;
+        if (wsBindingsActiveRef.current)
+            return; // Already bound
+        wsBindingsActiveRef.current = true;
+        const cleanup = bindReadyPhase(depsRef);
+        return () => {
+            wsBindingsActiveRef.current = false;
+            cleanup();
+        };
+    }, [readyPhaseReached, depsReady]);
+    // Desktop cold starts can briefly report an agent failure while the embedded
+    // runtime is still settling, especially when the renderer loads before the
+    // health/status routes are ready. Once the backend later reports a running
+    // agent, recover automatically instead of leaving the user stuck on the
+    // startup failure card until they manually press Retry.
+    const errorReason = state.phase === "error" ? state.reason : null;
+    useEffect(() => {
+        if (state.phase !== "error" || !depsReady)
+            return;
+        if (!errorReason || !isRecoverableStartupErrorReason(errorReason))
+            return;
+        if (typeof window === "undefined")
+            return;
+        const currentDeps = depsRef.current;
+        if (!currentDeps)
+            return;
+        const cancelled = { current: false };
+        // Schedule probes with exponential backoff (2.5s → cap 30s) and stop after
+        // a fixed number of attempts. Depending on `[state, ...]` here would
+        // re-arm this loop on every dispatch (each mints a new state object),
+        // turning a degraded backend into a perpetual probe storm that re-renders
+        // every useApp() consumer. Gate on the specific primitives the effect uses;
+        // other state fields are read through depsRef when a probe fires.
+        let timer = 0;
+        let attempt = 0;
+        const scheduleNext = () => {
+            if (cancelled.current || attempt >= RECOVERY_MAX_ATTEMPTS)
+                return;
+            const delay = Math.min(RECOVERY_BASE_DELAY_MS * 2 ** attempt, RECOVERY_MAX_DELAY_MS);
+            attempt += 1;
+            timer = window.setTimeout(() => {
+                void recoverTerminalStartupError(currentDeps, dispatch, cancelled)
+                    .then((recovered) => {
+                    // On success the dispatched event transitions out of "error", which
+                    // tears down this effect. Otherwise keep probing under backoff until
+                    // the attempt cap is reached, leaving the user-actionable Retry path.
+                    if (!recovered)
+                        scheduleNext();
+                })
+                    .catch(() => {
+                    scheduleNext();
+                });
+            }, delay);
+        };
+        scheduleNext();
+        return () => {
+            cancelled.current = true;
+            if (timer)
+                window.clearTimeout(timer);
+        };
+    }, [state.phase, errorReason, depsReady]);
+    // ── Public interface ─────────────────────────────────────────────
+    const retry = useCallback(() => dispatch({ type: "RETRY" }), []);
+    const reset = useCallback(() => {
+        _ctx.current = null;
+        effectRunRef.current += 1;
+        dispatch({ type: "RESET" });
+    }, []);
+    const pairingSuccess = useCallback(() => dispatch({ type: "PAIRING_SUCCESS" }), []);
+    const firstRunCompleteFn = useCallback(() => dispatch({ type: "FIRST_RUN_COMPLETE" }), []);
+    let target = null;
+    if (state.phase === "resolving-target")
+        target = state.target;
+    else if (state.phase === "polling-backend")
+        target = state.target;
+    else if (state.phase === "starting-runtime")
+        target = state.target;
+    return {
+        state,
+        dispatch,
+        retry,
+        reset,
+        pairingSuccess,
+        firstRunComplete: firstRunCompleteFn,
+        policy,
+        legacyPhase: toLegacyStartupPhase(state),
+        loading: isStartupLoading(state),
+        terminal: isStartupTerminal(state),
+        target,
+        phase: state.phase,
+    };
+}

package/state/useStreamingText.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Streaming-text primitive for the chat reducer.
+ *
+ * The chat pipeline only ever does six things to an in-flight assistant
+ * turn while a stream is alive:
+ *
+ *   - append a token (delta)        → mode: "append"
+ *   - replace text from a snapshot  → mode: "replace"
+ *   - apply final reconciled text   → mode: "complete"
+ *   - stamp a server failureKind    → mode: "fail"
+ *   - mark the turn as interrupted  → mode: "interrupt"
+ *   - drop an empty assistant turn  → mode: "drop"
+ *
+ * Every one of those used to be a hand-rolled `setMessages(prev => prev.map(...))`
+ * with subtly different equality checks scattered across `useChatSend.ts`
+ * and `useChatCallbacks.ts`. This primitive collapses them into a single
+ * map pass that:
+ *
+ *   - matches the target message by id,
+ *   - returns the previous array unchanged when the modification produces
+ *     no observable delta (referential equality preserved → no re-render),
+ *   - supports the same updater-fn semantics as React's `setState`.
+ *
+ * It deliberately does nothing structural (no inserts, no reorders) — those
+ * stay as direct `setConversationMessages` calls.
+ */
+import type { Dispatch, SetStateAction } from "react";
+import type { ChatFailureKind, ConversationMessage } from "../api";
+export type StreamingTextSetter = Dispatch<SetStateAction<ConversationMessage[]>>;
+/**
+ * One streaming-text mutation against a single in-flight assistant turn.
+ *
+ * `messageId` always identifies the assistant turn being modified. All other
+ * fields are mode-specific.
+ */
+export type StreamingTextModification = {
+    messageId: string;
+    mode: "append";
+    /** Raw delta token from the SSE stream. */
+    token: string;
+} | {
+    messageId: string;
+    mode: "replace";
+    /** Cumulative snapshot text from the SSE stream. */
+    fullText: string;
+} | {
+    messageId: string;
+    mode: "complete";
+    /** Final reconciled assistant text from the server. */
+    fullText: string;
+    /** Optional server-flagged failure class to stamp alongside the text. */
+    failureKind?: ChatFailureKind;
+    /** Optional agent reasoning/thought to stamp on the completed turn. */
+    reasoning?: string;
+} | {
+    messageId: string;
+    mode: "fail";
+    /** Server-flagged failure class. Text is left untouched. */
+    failureKind: ChatFailureKind;
+} | {
+    messageId: string;
+    mode: "interrupt";
+} | {
+    messageId: string;
+    mode: "drop";
+};
+/**
+ * Apply one streaming-text modification to the chat-message reducer.
+ *
+ * Returns referentially-equal `prev` when the modification is a no-op
+ * (target id missing, text already matches, failureKind already set, etc.).
+ */
+export declare function applyStreamingTextModification(setMessages: StreamingTextSetter, mod: StreamingTextModification): void;
+//# sourceMappingURL=useStreamingText.d.ts.map

package/state/useStreamingText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStreamingText.d.ts","sourceRoot":"","sources":["../../../../../src/state/useStreamingText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAGnE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,cAAc,CAAC,mBAAmB,EAAE,CAAC,CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,eAAe,CAAC;CAC9B,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAqDN;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,mBAAmB,EAChC,GAAG,EAAE,yBAAyB,GAC7B,IAAI,CAiBN"}

package/state/useStreamingText.js

@@ -0,0 +1,104 @@
+/**
+ * Streaming-text primitive for the chat reducer.
+ *
+ * The chat pipeline only ever does six things to an in-flight assistant
+ * turn while a stream is alive:
+ *
+ *   - append a token (delta)        → mode: "append"
+ *   - replace text from a snapshot  → mode: "replace"
+ *   - apply final reconciled text   → mode: "complete"
+ *   - stamp a server failureKind    → mode: "fail"
+ *   - mark the turn as interrupted  → mode: "interrupt"
+ *   - drop an empty assistant turn  → mode: "drop"
+ *
+ * Every one of those used to be a hand-rolled `setMessages(prev => prev.map(...))`
+ * with subtly different equality checks scattered across `useChatSend.ts`
+ * and `useChatCallbacks.ts`. This primitive collapses them into a single
+ * map pass that:
+ *
+ *   - matches the target message by id,
+ *   - returns the previous array unchanged when the modification produces
+ *     no observable delta (referential equality preserved → no re-render),
+ *   - supports the same updater-fn semantics as React's `setState`.
+ *
+ * It deliberately does nothing structural (no inserts, no reorders) — those
+ * stay as direct `setConversationMessages` calls.
+ */
+import { mergeStreamingText } from "./parsers.js";
+/**
+ * Compute the patched message for a single modification, or return `null`
+ * if the modification produces no observable change.
+ */
+function computeNextMessage(message, mod) {
+    switch (mod.mode) {
+        case "append": {
+            const nextText = mergeStreamingText(message.text, mod.token);
+            if (nextText === message.text)
+                return null;
+            return { ...message, text: nextText };
+        }
+        case "replace": {
+            if (mod.fullText === message.text)
+                return null;
+            return { ...message, text: mod.fullText };
+        }
+        case "complete": {
+            const sameText = message.text === mod.fullText;
+            const sameFailure = message.failureKind === mod.failureKind;
+            const sameReasoning = mod.reasoning === undefined || message.reasoning === mod.reasoning;
+            if (sameText && sameFailure && sameReasoning)
+                return null;
+            const next = { ...message, text: mod.fullText };
+            if (mod.failureKind) {
+                next.failureKind = mod.failureKind;
+            }
+            else if (message.failureKind !== undefined) {
+                delete next.failureKind;
+            }
+            if (mod.reasoning) {
+                next.reasoning = mod.reasoning;
+            }
+            return next;
+        }
+        case "fail": {
+            if (message.failureKind === mod.failureKind)
+                return null;
+            return { ...message, failureKind: mod.failureKind };
+        }
+        case "interrupt": {
+            if (message.interrupted === true)
+                return null;
+            return { ...message, interrupted: true };
+        }
+        case "drop":
+            // "drop" is a structural removal handled by the caller below — we
+            // only get here if the message exists, in which case the array
+            // changes by definition.
+            return message;
+    }
+}
+/**
+ * Apply one streaming-text modification to the chat-message reducer.
+ *
+ * Returns referentially-equal `prev` when the modification is a no-op
+ * (target id missing, text already matches, failureKind already set, etc.).
+ */
+export function applyStreamingTextModification(setMessages, mod) {
+    setMessages((prev) => {
+        if (mod.mode === "drop") {
+            const filtered = prev.filter((message) => message.id !== mod.messageId);
+            return filtered.length === prev.length ? prev : filtered;
+        }
+        let changed = false;
+        const next = prev.map((message) => {
+            if (message.id !== mod.messageId)
+                return message;
+            const patched = computeNextMessage(message, mod);
+            if (patched === null)
+                return message;
+            changed = true;
+            return patched;
+        });
+        return changed ? next : prev;
+    });
+}

package/state/useTabSync.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-window (same-origin) sync via BroadcastChannel.
+ *
+ * Opening the app in two browser windows/tabs of the same origin keeps the
+ * active conversation (and a small set of UI prefs) in sync, so switching
+ * conversations in one window reflects in the others without a round-trip to
+ * the server. Each window still owns its own per-connection server state; this
+ * only mirrors UI selection between windows of the *same* browser.
+ *
+ * Environments without BroadcastChannel (older webviews, SSR, some native
+ * shells) get an inert `publish*` surface and never receive callbacks.
+ */
+/** UI preferences mirrored across windows. Extend as new prefs need syncing. */
+export interface TabSyncPrefs {
+    language?: string;
+}
+export interface UseTabSyncOptions {
+    /** Called when another window changes its active conversation. */
+    onActiveConversation?: (conversationId: string | null) => void;
+    /** Called when another window updates synced UI prefs. */
+    onPrefs?: (prefs: TabSyncPrefs) => void;
+}
+export interface TabSyncApi {
+    /** Broadcast this window's active conversation to the other windows. */
+    publishActiveConversation: (conversationId: string | null) => void;
+    /** Broadcast updated UI prefs to the other windows. */
+    publishPrefs: (prefs: TabSyncPrefs) => void;
+    /** True when BroadcastChannel is available and wired up. */
+    enabled: boolean;
+}
+export declare function useTabSync(options?: UseTabSyncOptions): TabSyncApi;
+//# sourceMappingURL=useTabSync.d.ts.map

package/state/useTabSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTabSync.d.ts","sourceRoot":"","sources":["../../../../../src/state/useTabSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/D,0DAA0D;IAC1D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,yBAAyB,EAAE,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACnE,uDAAuD;IACvD,YAAY,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;CAClB;AAsBD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CA0DtE"}

package/state/useTabSync.js

@@ -0,0 +1,81 @@
+/**
+ * Cross-window (same-origin) sync via BroadcastChannel.
+ *
+ * Opening the app in two browser windows/tabs of the same origin keeps the
+ * active conversation (and a small set of UI prefs) in sync, so switching
+ * conversations in one window reflects in the others without a round-trip to
+ * the server. Each window still owns its own per-connection server state; this
+ * only mirrors UI selection between windows of the *same* browser.
+ *
+ * Environments without BroadcastChannel (older webviews, SSR, some native
+ * shells) get an inert `publish*` surface and never receive callbacks.
+ */
+import { useCallback, useEffect, useMemo, useRef } from "react";
+const TAB_SYNC_CHANNEL = "elizaos-tab-sync";
+function isTabSyncMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    if (kind === "active-conversation") {
+        const id = value.conversationId;
+        return id === null || typeof id === "string";
+    }
+    if (kind === "prefs") {
+        const prefs = value.prefs;
+        return typeof prefs === "object" && prefs !== null;
+    }
+    return false;
+}
+const NOOP_API = {
+    publishActiveConversation: () => { },
+    publishPrefs: () => { },
+    enabled: false,
+};
+export function useTabSync(options = {}) {
+    const channelRef = useRef(null);
+    // Keep callbacks in a ref so the channel subscription is set up once and
+    // never resubscribes when the parent re-renders with new handler identities.
+    const handlersRef = useRef(options);
+    handlersRef.current = options;
+    useEffect(() => {
+        if (typeof BroadcastChannel === "undefined")
+            return;
+        const channel = new BroadcastChannel(TAB_SYNC_CHANNEL);
+        channelRef.current = channel;
+        const onMessage = (event) => {
+            const data = event.data;
+            if (!isTabSyncMessage(data))
+                return;
+            if (data.kind === "active-conversation") {
+                handlersRef.current.onActiveConversation?.(data.conversationId);
+            }
+            else {
+                handlersRef.current.onPrefs?.(data.prefs);
+            }
+        };
+        channel.addEventListener("message", onMessage);
+        return () => {
+            channel.removeEventListener("message", onMessage);
+            channel.close();
+            channelRef.current = null;
+        };
+        // Intentionally empty deps: subscribe once; handlers are read via the ref.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const publishActiveConversation = useCallback((conversationId) => {
+        channelRef.current?.postMessage({
+            kind: "active-conversation",
+            conversationId,
+        });
+    }, []);
+    const publishPrefs = useCallback((prefs) => {
+        channelRef.current?.postMessage({
+            kind: "prefs",
+            prefs,
+        });
+    }, []);
+    const enabled = typeof BroadcastChannel !== "undefined";
+    // Return a stable object so consumers can list this in effect/callback deps
+    // without re-running on every render.
+    return useMemo(() => enabled ? { publishActiveConversation, publishPrefs, enabled } : NOOP_API, [enabled, publishActiveConversation, publishPrefs]);
+}

package/state/useTriggersState.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Trigger (heartbeat) state — extracted from AppContext.
+ *
+ * Manages trigger CRUD, run history, and health polling. Zero coupling to
+ * the startup sequence — triggers are only loaded post-ready.
+ */
+import type { CreateTriggerRequest, TriggerRunRecord, TriggerSummary, UpdateTriggerRequest } from "../api";
+export declare function useTriggersState(): {
+    state: {
+        triggers: import("@elizaos/shared").TriggerSummary[];
+        triggersLoaded: boolean;
+        triggersLoading: boolean;
+        triggersSaving: boolean;
+        triggerRunsById: Record<string, TriggerRunRecord[]>;
+        triggerHealth: import("@elizaos/shared").TriggerHealthSnapshot | null;
+        triggerError: string | null;
+    };
+    loadTriggers: (options?: {
+        silent?: boolean;
+    }) => Promise<void>;
+    loadTriggerHealth: () => Promise<void>;
+    loadTriggerRuns: (id: string) => Promise<void>;
+    ensureTriggersLoaded: () => Promise<void>;
+    createTrigger: (request: CreateTriggerRequest) => Promise<TriggerSummary | null>;
+    updateTrigger: (id: string, request: UpdateTriggerRequest) => Promise<TriggerSummary | null>;
+    deleteTrigger: (id: string) => Promise<boolean>;
+    runTriggerNow: (id: string) => Promise<boolean>;
+};
+//# sourceMappingURL=useTriggersState.d.ts.map

package/state/useTriggersState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTriggersState.d.ts","sourceRoot":"","sources":["../../../../../src/state/useTriggersState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,oBAAoB,EAEpB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACrB,MAAM,QAAQ,CAAC;AAgBhB,wBAAgB,gBAAgB;;;;;;;;;;6BAqBoB;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE;;0BA4BvB,MAAM;;6BAanC,oBAAoB,KAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;wBA2B/D,MAAM,WACD,oBAAoB,KAC5B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;wBA2BtB,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;wBA4BzB,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EAqDvC"}