@wix/himalaya-cli 0.1313.0 → 0.1314.0

package/templates/nonprofit-cause-owner/tier5-src/_shared/aria-chat.ts

@@ -37,6 +37,7 @@ import {
   functionCallsOf,
   getConversationMessages,
   getConversations,
+  getSuggestedActions,
   itemsOf,
   listInstalledProviders,
   mentionReference,
@@ -46,6 +47,7 @@ import {
   queryItems,
   sendFunctionCallResults,
   sendMessage,
+  suggestedActionsOf,
   triggerAssistantMessage,
   uploadTargetUrl,
   userMessageIdOf,
@@ -186,6 +188,26 @@ export interface AriaChatState {
   messagesHidden: boolean;
   /** Non-empty ONLY on the greeting-only empty state. */
   prompts: AriaPromptChip[];
+  /** Collapses the loading placeholder that stands in for `prompts` while this
+   *  conversation's suggestions are being fetched (`AriaChatOptions.suggestions`).
+   *  Derived in `gated`, like `stopHidden`: shown only while a fetch is out AND
+   *  the owner has not said anything yet. */
+  promptsLoadingHidden: boolean;
+  /** The service's suggestions for THIS conversation, as cards — fetched once
+   *  when the conversation's empty state was minted, and kept with it, so a later
+   *  `load` or `tick` redraws the same cards instead of asking again. Empty means
+   *  "none": the app's own `prompts` are drawn instead. */
+  _suggested: AriaPromptChip[];
+  /** The fetch this state is waiting on, or "". Only the outcome carrying THIS
+   *  token may land — one minted for a conversation the owner has since left
+   *  (➕, a business switch) is dropped. */
+  _suggestToken: string;
+  /** Whether THIS conversation has been through the suggestions step at all.
+   *  False only on a conversation minted before an app passed `suggestions` —
+   *  a persisted snapshot from an older bundle, overlaid on these defaults at a
+   *  cold boot. Its empty `_suggested` would otherwise read as "the service had
+   *  none" and keep the fallback cards on screen until the owner pressed ➕. */
+  _suggestAsked: boolean;
   _convId: string;
   /** The metaSite the conversation belongs to. Conversations are scoped to the
    *  signed instance that created them, so a site switch must not resume one. */
@@ -524,7 +546,76 @@ export interface AriaAttachmentPorts {
   settled(outcome: AriaAttachmentOutcome): void;
 }
 
+/** Server-provided prompt cards — the chat-service's sibling knowledge service
+ *  (`getSuggestedActions`), which the native Aria app fetches once per
+ *  conversation, keeps the top 3 of, and caches for an hour.
+ *
+ *  Omit it and the empty state shows `AriaChatOptions.prompts`, exactly as before.
+ *  Supply it and those become the FALLBACK: drawn whenever the service answers
+ *  nothing or fails — which in a published web app is always, because it refuses
+ *  a url off the gateway (`webwix_owner_only`). */
+export interface AriaSuggestionOptions {
+  /** Hand a finished fetch back to the service as a NEW action
+   *  (`suggestionsSettled`), with the token it was started under. A fresh dispatch
+   *  rather than a return value for the reason `AriaAttachmentPorts.settled` is
+   *  one: the fetch must not hold the greeting off the screen, so the action that
+   *  starts it returns first, with a loading placeholder where the cards go.
+   *
+   *  Return the dispatch's promise. A settle can arrive in the instant between a
+   *  newer action computing its result and the runtime committing it, when there
+   *  is nothing it may safely change; the worker then dispatches it again once
+   *  that promise resolves, and stops as soon as the cards have landed. */
+  settled(token: string): void | Promise<unknown>;
+  /** The owner's language, as BCP-47. Part of the cache key. Default: whatever
+   *  the worker runtime reports (`runtimeLocale`), else `"en"`. */
+  locale?: () => string;
+  /** The glyph on every server card. The service sends none, and the card has a
+   *  slot for one; the app's own cards keep their own. */
+  emoji?: string;
+  /** WHO the suggestions are for — the signed-in account, as any stable string.
+   *  The service answers on the account's cookie, so its suggestions belong to the
+   *  account, not only to the site: two owners of one business can be told
+   *  different things. The cache is keyed on this as well as site + locale, and is
+   *  emptied whenever it changes, so a worker that outlives a sign-out never shows
+   *  the previous owner's cards.
+   *
+   *  Omit it, or let it resolve `""` or throw, and the account is UNKNOWN: every
+   *  conversation then asks the service afresh and nothing is cached, because a
+   *  cache that cannot tell two accounts apart must not be shared between them. */
+  principal?: () => string | Promise<string>;
+}
+
+/** How many suggestions become cards. The native Aria app's number. */
+export const ARIA_SUGGESTION_LIMIT = 3;
+/** How long one site + locale's suggestions are reused before being asked for
+ *  again. The native Aria app's number. */
+export const ARIA_SUGGESTION_TTL_MS = 60 * 60 * 1000;
+/** How many conversations' suggestion fetches the worker keeps an answer for
+ *  until they land. Overlapping actions mint one each; only the oldest are
+ *  pruned past this, never a newer one's. */
+export const ARIA_SUGGESTION_PENDING_LIMIT = 8;
+
+/** The owner's locale as the worker runtime knows it: the browser's on the web,
+ *  `Intl` where the engine ships it (JavaScriptCore, Hermes), else `"en"` — the
+ *  service's own default, and what QuickJS (no `Intl`) falls back to. Never
+ *  throws. */
+export function runtimeLocale(): string {
+  try {
+    const nav = (globalThis as { navigator?: { language?: unknown } }).navigator;
+    if (typeof nav?.language === "string" && nav.language.trim()) return nav.language.trim();
+  } catch { /* no navigator */ }
+  try {
+    const intl = (globalThis as { Intl?: { DateTimeFormat?: () => { resolvedOptions(): { locale?: unknown } } } }).Intl;
+    const loc = intl?.DateTimeFormat?.().resolvedOptions().locale;
+    if (typeof loc === "string" && loc.trim()) return loc.trim();
+  } catch { /* no Intl */ }
+  return "en";
+}
+
 export interface AriaChatOptions {
+  /** Server-provided prompt cards, with `prompts` as the fallback. See
+   *  `AriaSuggestionOptions`. */
+  suggestions?: AriaSuggestionOptions;
   /** Photo attachments in the composer. Omit it and the attach actions are
    *  inert — which is also what the descriptor does, since it paints no attach
    *  control unless the app passes the matching actions. */
@@ -1496,6 +1587,12 @@ export interface AriaChatCore {
    *  carries the rest of the turn, at the full rate. */
   streamEnded(s: AriaChatState): AriaChatState;
   streamFailed(s: AriaChatState, err?: unknown): AriaChatState;
+  /** A suggestions fetch finished (`AriaSuggestionOptions.settled`). The arg names
+   *  the token it was started under (`{ id }` or the bare string); the cards
+   *  themselves never ride the dispatch — only the token does. An outcome for a
+   *  conversation the owner has since left changes nothing — the action then
+   *  resolves `undefined`, which leaves the stored state untouched. */
+  suggestionsSettled(s: AriaChatState, arg?: AriaActionArg): AriaChatState | undefined;
 }
 
 const POLL_ID = "aria-turn";
@@ -1576,6 +1673,211 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   };
   const toolFailedText = () => res(o.labels?.toolFailed ?? `${assistant()} couldn't finish that. Try again.`);
   const promptList = () => res(o.prompts).map((p) => ({ ...p, label: promptLabel(p) }));
+
+  // ---- Server suggestions (see `AriaSuggestionOptions`) --------------------
+  //
+  // The cache lives HERE, in worker memory, keyed by site + locale and aged by
+  // `Date.now()` — a worker has no timer, so "cached for an hour" is a timestamp
+  // compared when the next conversation asks, never an expiry that fires. It does
+  // not survive the process, which is the right failure: a cold start asks once.
+  // What DOES survive is each conversation's own cards (`_suggested`), because
+  // they ride the persisted state — so a conversation never changes its cards
+  // under the owner, even when the cache entry it came from expires.
+  const suggestionCache = new Map<string, { at: number; chips: AriaPromptChip[] }>();
+  /** One request per account + site + locale at a time: a `load` and a ➕ racing
+   *  share it. */
+  const suggestionFetches = new Map<string, Promise<AriaPromptChip[]>>();
+  /** The account the cache and the in-flight fetches belong to. Both are emptied
+   *  the moment a different one asks (`AriaSuggestionOptions.principal`). */
+  let suggestionPrincipal = "";
+  /** The signed-in account, or `""` when it cannot be told. Never throws. */
+  const principalNow = async (): Promise<string> => {
+    const read = o.suggestions?.principal;
+    if (!read) return "";
+    try { return String((await read()) ?? "").trim(); } catch { return ""; }
+  };
+  /** What each token's fetch came back with, and WHOSE it is: the business,
+   *  account and language it was asked for. `chips` is `null` while the fetch is
+   *  out; a failure is recorded as `[]`, so the app's own prompts are drawn.
+   *
+   *  An outcome lands only on a state of exactly its own scope (see
+   *  `withSettledSuggestions`) — never on a state whose business, account or
+   *  language has moved on, however the commits interleave. And a placeholder
+   *  whose token is not here at all (pruned, from a previous process, or dropped
+   *  for its scope) is never left waiting: it falls back to the app's own cards
+   *  and the next `load` asks again. That guarantee is what lets this map be
+   *  bounded (ARIA_SUGGESTION_PENDING_LIMIT) without ever stranding a skeleton. */
+  interface SuggestOutcome { site: string; principal: string; locale: string; convId: string; chips: AriaPromptChip[] | null }
+  const suggestOutcomes = new Map<string, SuggestOutcome>();
+  /** The language the suggestions are asked in right now. Never throws. */
+  const localeNow = (): string => {
+    try { return (o.suggestions?.locale ?? runtimeLocale)() || "en"; } catch { return "en"; }
+  };
+  /** Tokens whose cards have landed at least once — ends `hand`'s re-dispatch. */
+  const landedTokens = new Set<string>();
+  let suggestSeq = 0;
+  const nowMs = (): number => { try { return Date.now(); } catch { return 0; } };
+  const suggestionEmoji = o.suggestions?.emoji ?? "✨";
+  /** The cards a conversation shows: its own suggestions when it has any, the
+   *  app's prompts otherwise — and NOTHING while its fetch is still out, where the
+   *  loading placeholder stands in. */
+  const chipsOf = (s: Pick<AriaChatState, "_suggested" | "_suggestToken">): AriaPromptChip[] =>
+    s._suggestToken ? [] : s._suggested && s._suggested.length ? s._suggested : promptList();
+  /** `key` is `""` for an UNKNOWN account: the answer is then neither shared with
+   *  a racing request nor cached. */
+  const fetchSuggestions = (key: string, locale: string): Promise<AriaPromptChip[]> => {
+    const running = key ? suggestionFetches.get(key) : undefined;
+    if (running) return running;
+    const started = getSuggestedActions({ assistantId: o.assistantId, locale }).then((r) => {
+      const list: AriaPromptChip[] = suggestedActionsOf(r).slice(0, ARIA_SUGGESTION_LIMIT).map((a, i) => {
+        // `title` is what the card says and `text` is what it SENDS — the
+        // service's `respondText`, a different string on purpose. `description`
+        // is not drawn: the native Aria app's suggestion card shows the title
+        // alone on both platforms (ChatEmptyState.swift / ChatEmptyState.kt in
+        // wix-private/aria-native-apps), so `sub` stays empty and the card is one
+        // line whether the service sends a description or not.
+        const chip = { id: `sg${i + 1}`, emoji: suggestionEmoji, title: a.title, sub: "", text: a.respondText };
+        return { ...chip, label: promptLabel(chip) };
+      });
+      // An empty answer is an answer, and is cached like any other. A FAILURE is
+      // not: the next conversation asks again. Only an entry still registered as
+      // in flight is cached — one the account switch below already dropped belongs
+      // to the previous owner.
+      if (key && suggestionFetches.get(key) === started) {
+        suggestionCache.set(key, { at: nowMs(), chips: list });
+        suggestionFetches.delete(key);
+      }
+      return list;
+    }, (e: unknown) => {
+      if (key && suggestionFetches.get(key) === started) suggestionFetches.delete(key);
+      throw e;
+    });
+    if (key) suggestionFetches.set(key, started);
+    return started;
+  };
+  /** `next` with this conversation's suggestions attached: from the cache when a
+   *  fresh entry exists, otherwise a fetch is started and `next` shows the
+   *  placeholder until `suggestionsSettled` lands. Called ONLY where a
+   *  conversation's empty state is minted — that is what makes the fetch once per
+   *  conversation rather than once per `load`. */
+  const withSuggestions = async (next: AriaChatState, site: string): Promise<AriaChatState> => {
+    const port = o.suggestions;
+    if (!port) return next;
+    // A conversation the owner has already spoken in shows no cards at all.
+    if (next.messages.some((b) => b.role === "USER")) return { ...next, _suggested: [], _suggestToken: "", _suggestAsked: true };
+    const locale = localeNow();
+    // The answer is the ACCOUNT's (it rides the account cookie), so a different
+    // account empties the cache rather than being served the last one's cards.
+    const principal = await principalNow();
+    if (principal !== suggestionPrincipal) {
+      suggestionCache.clear();
+      suggestionFetches.clear();
+      suggestionPrincipal = principal;
+    }
+    const key = principal ? `${principal}|${site}|${locale}` : "";
+    const hit = key ? suggestionCache.get(key) : undefined;
+    const now = nowMs();
+    // `now >= at` too: a clock that went BACKWARDS would make an entry look fresh
+    // for as long as it stays behind, so it is treated as expired instead.
+    if (hit && now >= hit.at && now - hit.at < ARIA_SUGGESTION_TTL_MS) {
+      const ready = { ...next, _suggested: hit.chips, _suggestToken: "", _suggestAsked: true };
+      return { ...ready, prompts: promptsFor(ready.messages, chipsOf(ready)) };
+    }
+    suggestSeq += 1;
+    // Stamped with the clock as well as the counter: the counter restarts with the
+    // process, and a persisted token from the previous one must not match a new one.
+    const token = `sg-${now}-${suggestSeq}`;
+    // Every token keeps its OWN entry, bound to its scope. Not "only the newest
+    // can matter": actions are not serialized, so an older `load` or ➕ that minted
+    // its token first can still COMMIT last, putting that older token on screen —
+    // and its answer must then still be here to land (or be refused for its
+    // scope). Kept after landing, too, so a stale commit that puts the token back
+    // is cleared again by the next `gated`. Pruned only as the oldest past the
+    // bound; a pruned token that is still on screen falls back rather than waits.
+    // With NO identity to tell owners apart (`principal` is ""), the only thing
+    // that changes when one owner signs out and another signs in on the same
+    // business is the conversation: a sign-in opens a new one. So an
+    // unknown-account answer is bound to the conversation it was asked for, and
+    // a new conversation drops every other conversation's unknown-account answer
+    // still out — a late one must never reach the next owner's screen. (A
+    // dropped answer is not a stuck placeholder: see `withSettledSuggestions`.)
+    if (!principal) {
+      for (const [other, entry] of suggestOutcomes) {
+        if (!entry.principal && entry.convId !== next._convId) {
+          suggestOutcomes.delete(other);
+          landedTokens.delete(other);
+        }
+      }
+    }
+    suggestOutcomes.set(token, { site, principal, locale, convId: next._convId, chips: null });
+    while (suggestOutcomes.size > ARIA_SUGGESTION_PENDING_LIMIT) {
+      const oldest = suggestOutcomes.keys().next().value;
+      if (oldest === undefined) break;
+      suggestOutcomes.delete(oldest);
+      landedTokens.delete(oldest);
+    }
+    const hand = (chips: AriaPromptChip[]) => {
+      const entry = suggestOutcomes.get(token);
+      if (!entry) return;
+      entry.chips = chips;
+      // Dispatch the settle, and again after each one resolves while the outcome
+      // is still waiting: the action that minted this token may have computed its
+      // result but not yet had it committed, and a settle in that instant can only
+      // leave the state alone (see `suggestionsSettled`). The outcome leaving the
+      // map — landed, or dropped for a newer conversation — ends it; so does the
+      // bound, after which the next commit applies it (`gated`).
+      let tries = 0;
+      const attempt = (): void => {
+        if (suggestOutcomes.get(token)?.chips !== chips || landedTokens.has(token) || tries >= 5) return;
+        tries += 1;
+        let sent: unknown;
+        try { sent = port.settled(token); } catch { return; }
+        if (sent && typeof (sent as Promise<unknown>).then === "function") (sent as Promise<unknown>).then(attempt, () => {});
+      };
+      attempt();
+    };
+    fetchSuggestions(key, locale).then(hand, () => hand([]));
+    return { ...next, _suggested: [], _suggestToken: token, _suggestAsked: true, prompts: [] };
+  };
+  /** `s` with its fetch's cards in place, when that fetch has finished; `s`
+   *  itself otherwise. Run on every commit (`gated`) as well as by
+   *  `suggestionsSettled`, so the cards land on whichever comes first — the
+   *  settle dispatch, or the commit of the action that started the fetch. */
+  const withSettledSuggestions = (s: AriaChatState): AriaChatState => {
+    const token = s._suggestToken;
+    if (!token) return s;
+    const entry = suggestOutcomes.get(token);
+    // A placeholder nobody holds an answer for — pruned past the bound, minted by a
+    // previous process, or dropped below for its scope — must not wait for good.
+    // It shows the app's own cards now, and `_suggestAsked: false` makes the next
+    // `load` ask again, for whatever scope it is in by then.
+    if (!entry) return asksAgain(s);
+    // The answer is ONE business's, account's and language's. A commit that puts
+    // this token on a state of another scope — or after the owner has moved to
+    // another business or signed in as someone else — must not show it there.
+    // An unknown-account answer goes to its OWN conversation only, and never to one
+    // with no id (a failed create), where nothing ties it to an owner.
+    const unknownElsewhere = !entry.principal && (!entry.convId || entry.convId !== s._convId);
+    if (entry.site !== s._siteId || entry.site !== siteOf() || entry.principal !== suggestionPrincipal
+      || entry.locale !== localeNow() || unknownElsewhere) {
+      suggestOutcomes.delete(token);
+      landedTokens.delete(token);
+      return asksAgain(s);
+    }
+    // Still out: the placeholder is right where it is.
+    if (!entry.chips) return s;
+    // NOT deleted: a later commit of a state from before this one can carry the
+    // same token back, and it must land again rather than wait forever.
+    landedTokens.add(token);
+    const ready: AriaChatState = { ...s, _suggestToken: "", _suggested: entry.chips };
+    return { ...ready, prompts: promptsFor(ready.messages, chipsOf(ready)) };
+  };
+  /** `s` without its placeholder: the app's own cards, and asked for afresh on the
+   *  next `load` (which only re-asks a conversation that has not been asked). */
+  const asksAgain = (s: AriaChatState): AriaChatState => {
+    const fresh: AriaChatState = { ...s, _suggestToken: "", _suggested: [], _suggestAsked: false };
+    return { ...fresh, prompts: promptsFor(fresh.messages, chipsOf(fresh)) };
+  };
   const siteOf = o.siteId ?? (() => "");
   const resumeOf = o.resumeConversationId ?? inputConversationId;
   const historyKeyFor = (site: string) => scopedKey(o.historyKey, site);
@@ -1683,7 +1985,8 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
 
   const initialState: AriaChatState = {
     status: "loading", statusText: "", error: "", input: "", copyNote: "", replyActionsHidden: true,
-    messages: [], messagesHidden: true, prompts: [], _convId: "", _siteId: "", _pending: "", _pendingRefs: "", _pendingAttach: [],
+    messages: [], messagesHidden: true, prompts: [], promptsLoadingHidden: true, _suggested: [], _suggestToken: "", _suggestAsked: false,
+    _convId: "", _siteId: "", _pending: "", _pendingRefs: "", _pendingAttach: [],
     _pendingAfter: 0, _pendingId: "", _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
     _abortId: "", _turnId: "", stopHidden: true, ok: false,
     listening: false, micHidden: !o.dictation, listeningHidden: true,
@@ -2885,8 +3188,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   };
   const gated = (input: AriaChatState): AriaChatState => {
     mentionSite();
-    // The live reply first, so every rule below sees what will be painted.
-    const s = withLive(input);
+    // A suggestions fetch that finished before this commit lands now — see
+    // `withSettledSuggestions`, and `suggestionsSettled` for why its own
+    // dispatch can arrive too early to. Then the live reply, so every rule
+    // below sees what will be painted.
+    const s = withLive(withSettledSuggestions(input));
     // Stop goes once the stream says the model has finished writing: there is
     // nothing left for an abort to save, and the turn only waits on the server
     // to close it.
@@ -2902,6 +3208,9 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     const listening = s.listening === true;
     const micHidden = !o.dictation || dictationAvailable === false || listening;
     const listeningHidden = !listening;
+    // The suggestions placeholder: shown only while a fetch is out AND the owner
+    // has not said anything yet (a message sent meanwhile empties the cards).
+    const promptsLoadingHidden = !s._suggestToken || s.messages.some((b) => b.role === "USER");
     // The transcript scroll + the character, derived here for the reason the gates above
     // are: one exit every action passes through, so no reducer can leave a stale
     // anchor pointing at a row that has since been replaced, or a character still
@@ -2912,7 +3221,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     const talking = inFlight && replyStarted(s.messages);
     const charThinkingHidden = !(inFlight && !talking);
     const charTalkingHidden = !talking;
-    const heroHidden = !(s.prompts && s.prompts.length > 0);
+    // The empty state is still the empty state while its suggestions are out:
+    // the placeholder stands where the cards go, so the hero and the gap rules
+    // treat it as cards on screen rather than flickering the character away.
+    const heroHidden = !((s.prompts && s.prompts.length > 0) || !promptsLoadingHidden);
     const promptsGapHidden = !heroHidden;
     const messagesHidden = s.messages.length === 0;
     const statusHidden = !s.statusText && charThinkingHidden && charTalkingHidden;
@@ -2921,9 +3233,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       && s.scrollAnchor === scrollAnchor && s.charThinkingHidden === charThinkingHidden
       && s.charTalkingHidden === charTalkingHidden && s.heroHidden === heroHidden && s.messagesHidden === messagesHidden
       && s.statusHidden === statusHidden && s.promptsGapHidden === promptsGapHidden
+      && s.promptsLoadingHidden === promptsLoadingHidden
       ? s
       : { ...s, stopHidden: hidden, replyActionsHidden, micHidden, listeningHidden,
-          scrollAnchor, charThinkingHidden, charTalkingHidden, heroHidden, messagesHidden, statusHidden, promptsGapHidden };
+          scrollAnchor, charThinkingHidden, charTalkingHidden, heroHidden, messagesHidden, statusHidden, promptsGapHidden, promptsLoadingHidden };
     // The attachment projection rides the same exit, for the same reason: one
     // place that every action's result passes through, so no reducer can hand
     // back a stale copy of the chips. Seeded first, so the very first action of
@@ -3131,10 +3444,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
           // `copyNote: ""` — a resumed transcript ends in a reply, so the row is
           // shown at once; a note carried over would say "Copied" beside an
           // answer from a different conversation that nobody copied.
-          return leaving(await withWidgetItems({ ...s, status: "ready", _convId: resumeId, _siteId: site, _pending: "", statusText: "", error: "", copyNote: "",
-            messages: resumed, ...observed(raw, s.widget), prompts: promptsFor(resumed, promptList()),
+          return leaving(await withWidgetItems(await withSuggestions({ ...s, status: "ready", _convId: resumeId, _siteId: site, _pending: "", statusText: "", error: "", copyNote: "",
+            messages: resumed, ...observed(raw, s.widget), _suggested: [], _suggestToken: "", prompts: promptsFor(resumed, promptList()),
             // Transcript scroll — open a resumed conversation at its latest turn, pinning nothing.
-            ...openedAtLatest(s, resumed) }));
+            ...openedAtLatest(s, resumed) }, site)));
         } catch { /* expired or unreachable — fall through to a fresh one */ }
       }
       // Opening a screen runs `load` more than once — the bundle self-kicks at
@@ -3166,15 +3479,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // Transcript scroll — a conversation rehydrated with no send token (state persisted
         // before tokens existed) still opens at its latest turn.
         const opened = s.scrollSend || isGreetingOnly(messages) ? {} : openedAtLatest(s, messages);
-        return { ...s, status: "ready", messages, prompts: promptsFor(messages, promptList()), ...opened };
+        const reused: AriaChatState = { ...s, status: "ready", messages, prompts: promptsFor(messages, chipsOf(s)), ...opened };
+        // A persisted state can be waiting on a fetch that died with the previous
+        // process; nothing would ever settle it, so ask again. And one minted by a
+        // bundle from before the suggestions existed never asked at all — the
+        // update every owner's last conversation goes through — so it asks now.
+        const orphaned = !!s._suggestToken && !suggestOutcomes.has(s._suggestToken);
+        return orphaned || (!!o.suggestions && !s._suggestAsked) ? await withSuggestions(reused, site) : reused;
       }
       try {
-        return leaving({ ...s, status: "ready", _convId: await createOnce(site), _siteId: site, _pending: "", statusText: "",
-          messages: greetingOnly(), ...observed([]), prompts: promptList(), ...SCROLL_RESET });
+        return leaving(await withSuggestions({ ...s, status: "ready", _convId: await createOnce(site), _siteId: site, _pending: "", statusText: "",
+          messages: greetingOnly(), ...observed([]), prompts: promptList(), ...SCROLL_RESET }, site));
       } catch (e) {
         // Even if create fails, show the greeting; submit retries the create.
-        return leaving({ ...s, status: "ready", _convId: "", _siteId: site, _pending: "", ...failureSlots(e, unavailableText),
-          messages: greetingOnly(), ...observed([]), prompts: promptList(), ...SCROLL_RESET });
+        return leaving(await withSuggestions({ ...s, status: "ready", _convId: "", _siteId: site, _pending: "", ...failureSlots(e, unavailableText),
+          messages: greetingOnly(), ...observed([]), prompts: promptList(), ...SCROLL_RESET }, site));
       }
     },
 
@@ -3265,12 +3584,12 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // and the old observed counts back — the fresh chat snapping back to the
         // previous one, which reads as ➕ having done nothing.
         turnSeq += 1;
-        return slow({ ...s, ...retired, status: "ready", _convId: conversationIdOf(res), _siteId: site, input: "", statusText: "", error: "",
-          _pending: "", _abortId: "", _turnId: "", copyNote: "", messages: greetingOnly(), ...observed([]), prompts: promptList(), ok: false, ...SCROLL_RESET });
+        return slow(await withSuggestions({ ...s, ...retired, status: "ready", _convId: conversationIdOf(res), _siteId: site, input: "", statusText: "", error: "",
+          _pending: "", _abortId: "", _turnId: "", copyNote: "", messages: greetingOnly(), ...observed([]), prompts: promptList(), ok: false, ...SCROLL_RESET }, site));
       } catch (e) {
         turnSeq += 1;   // see above — a failed create commits state too
-        return slow({ ...s, ...retired, status: "ready", _convId: "", _siteId: site, input: "", ...failureSlots(e, unavailableText),
-          _pending: "", _abortId: "", _turnId: "", copyNote: "", messages: greetingOnly(), ...observed([]), prompts: promptList(), ok: false, ...SCROLL_RESET });
+        return slow(await withSuggestions({ ...s, ...retired, status: "ready", _convId: "", _siteId: site, input: "", ...failureSlots(e, unavailableText),
+          _pending: "", _abortId: "", _turnId: "", copyNote: "", messages: greetingOnly(), ...observed([]), prompts: promptList(), ok: false, ...SCROLL_RESET }, site));
       }
     },
 
@@ -3347,7 +3666,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
           messages: painted,
           _pending: failed ? "" : pending,
           ...observed(raw, s.widget),
-          prompts: promptsFor(painted, promptList()),
+          prompts: promptsFor(painted, chipsOf(s)),
           statusText: ended ? "" : s.statusText,
           ...(ended ? { _abortId: "" } : {}),
           ...(failed ? toolFailureSlots(failed) : {}),
@@ -3833,6 +4152,29 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       return { ...withoutNotice(latest()), error: "" };
     },
 
+    suggestionsSettled: (s, arg) => {
+      const token = typeof arg === "string" ? arg.trim() : typeof arg === "object" && arg ? String(arg.id ?? "").trim() : "";
+      if (!token) return undefined;
+      // The cards come from the worker's own memory, never the dispatch: only the
+      // token rides the action, so no host's arg marshalling can mangle them.
+      //
+      // A token that does not match is left alone rather than dropped. It is
+      // either stale — ➕ or a business switch minted a newer one — or the action
+      // that minted it has not COMMITTED yet: `load` awaits more work after its
+      // reducer returns, so this settle can run against the state from before it.
+      // In that case the outcome is still waiting, and `gated` applies it on that
+      // commit — whichever action commits it, and in whatever order.
+      //
+      // Either way the answer is `undefined`, NOT `s`. The runtime commits whatever
+      // an action returns, and this one reads its state when it is dispatched: a
+      // settle that lands while a slower action (a business switch's `load`) is
+      // still running would commit the state from before that action and wipe out
+      // its result. `undefined` is the runtime's "change nothing".
+      if (token !== s._suggestToken) return undefined;
+      const landed = withSettledSuggestions(s);
+      return landed === s ? undefined : landed;
+    },
+
     attachmentSettled: (s, arg) => {
       const id = chipIdOf(arg);
       if (!id) return s;
@@ -4111,6 +4453,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     mentionRemove: (s, arg) => gated(impl.mentionRemove(s, arg)),
     attach: (s, arg) => impl.attach(s, arg).then(gated),
     attachmentSettled: (s, arg) => gated(impl.attachmentSettled(s, arg)),
+    suggestionsSettled: (s, arg) => {
+      const r = impl.suggestionsSettled(s, arg);
+      return r ? gated(r) : r;
+    },
     removeAttachment: (s, arg) => gated(impl.removeAttachment(s, arg)),
     retryAttachment: (s, arg) => gated(impl.retryAttachment(s, arg)),
     streamEvent: (s, event) => impl.streamEvent(s, event).then((r) => (r ? gated(r) : r)),

package/templates/nonprofit-cause-owner/tier5-src/himi-owner-lite-aria/index.ts

@@ -31,6 +31,7 @@ import { availability, recognizeOnce, stop as stopSpeech } from "@himalaya/speec
 import { capturePhoto } from "@himalaya/camera";
 import { put } from "@himalaya/presigned-upload";
 import { alert } from "@himalaya/ui";
+import { auth } from "@himalaya/wix-platform";
 import {
   activeSiteId,
   createAriaChat,
@@ -193,7 +194,24 @@ const core = createAriaChat({
     "ownerAria.greeting",
     "Hi, I'm Aria, your business and web design expert.\nI'm here to help you complete tasks, answer questions, create content and guide you to useful features.",
   ),
+  // The four cards above are the FALLBACK now: the service's own suggestions for
+  // this business replace them when it has any. It answers on device with
+  // the owner's account cookie; a published web app refuses the call outright
+  // (`webwix_owner_only`), so there it always draws the four.
   prompts,
+  suggestions: {
+    // A NEW action, for the reason `attachments.settled` below is one: the fetch
+    // must not hold the greeting back, so `load` returns first and the cards land
+    // after it. `svc` is read at call time, long after it exists.
+    settled: (token) => svc.suggestionsSettled({ id: token }),
+    // The suggestions are the signed-in ACCOUNT's (the call rides its cookie), so
+    // the cache is keyed on who that is and emptied when it changes. An identity
+    // the host cannot read is "", which turns the cache off rather than sharing it:
+    // every conversation then asks once, fresh. That is the case on __HIMI_APP_NAME__'s
+    // native shells today, which do not register the wix_platform capability, so
+    // `authIdentity` is refused there and the cache stays off.
+    principal: async () => (await auth.getIdentity()).userId ?? "",
+  },
   labels: {
     assistant: () => copyParam("ownerAria.name", "Aria"),
     you: () => copyParam("ownerAria.you", "You"),
@@ -351,6 +369,7 @@ const svc = defineService<AriaChatState, {
   attachmentSettled: (s: AriaChatState, arg?: AriaActionArg) => AriaChatState;
   removeAttachment: (s: AriaChatState, arg?: AriaActionArg) => AriaChatState;
   retryAttachment: (s: AriaChatState, arg?: AriaActionArg) => AriaChatState;
+  suggestionsSettled: (s: AriaChatState, arg?: AriaActionArg) => AriaChatState | undefined;
 }>(SERVICE, {
   state: core.initialState,
   actions: {
@@ -418,6 +437,9 @@ const svc = defineService<AriaChatState, {
     streamEvent: core.streamEvent,
     streamEnded: core.streamEnded,
     streamFailed: core.streamFailed,
+    // The empty state's server suggestions landing. Dispatched by the
+    // fetch itself (see `suggestions.settled` above), never by the descriptor.
+    suggestionsSettled: core.suggestionsSettled,
   },
 });
 

package/templates/owner-lite/dev/index.ts

@@ -57234,6 +57234,27 @@ const SCREENS = runtimeSetting({
                 "hiddenPath": "$service:himiOwnerLiteAria.replyActionsHidden"
               }
             },
+            {
+              "id": "himi_owner_lite_aria.prompts.loading",
+              "body": {
+                "package": "himalaya",
+                "type": "Skeleton",
+                "props": {
+                  "height": 48,
+                  "cornerRadius": 12,
+                  "count": 3
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteAria.promptsLoadingHidden",
+                "padding": {
+                  "leading": 0,
+                  "trailing": 0,
+                  "top": 0,
+                  "bottom": 0
+                }
+              }
+            },
             {
               "id": "himi_owner_lite_aria.prompts",
               "body": {
@@ -61354,7 +61375,8 @@ const SCREENS = runtimeSetting({
         "speech",
         "camera",
         "presigned_upload",
-        "stream"
+        "stream",
+        "wix_platform"
       ],
       "minBinaryVersion": "0.1.0",
       "bundleVersion": "0.0.1"