@wix/himalaya-cli 0.940.0 → 0.942.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/genie-chat/src/index.d.ts

@@ -78,7 +78,21 @@ export interface GetConversationsResponse {
 export interface SendMessageResponse {
     assistantMessages?: ConversationMessage[];
     conversationMessage?: ConversationMessage;
+    /** The user's own turn AS STORED by the service — present on step 1's reply
+     *  (`conversationUserMessage`), which is where the id actually comes from. */
+    userMessage?: ConversationMessage;
+    /** The id the owner's turn was stored under, carried out by `sendMessage`.
+     *
+     *  The only handle the abort route accepts, and there is no route that looks
+     *  it up afterwards — so a caller that wants to stop the reply has to keep it
+     *  from the send. `sendMessage` resolves with step 2's response, which does
+     *  NOT carry `userMessage`, so this field is the one reliable source; read it
+     *  through `userMessageIdOf` rather than directly. */
+    userMessageId?: string;
 }
+/** Empty on success — the service answers `{}`. Named rather than `void` so a
+ *  future field has somewhere to land without changing every call site. */
+export type AbortAssistantMessageGenerationResponse = Record<string, never>;
 export interface GetConversationMessagesResponse {
     messages?: ConversationMessage[];
     conversationMessages?: ConversationMessage[];
@@ -149,10 +163,28 @@ export declare function sendMessage(conversationId: string, content: string, mod
  *  failed — see `sendMessage`, which attaches the id to its error for exactly
  *  this call. Carries no content: the turn it names is the content. */
 export declare function triggerAssistantMessage(conversationId: string, userMessageId: string, opts?: SendMessageOptions): Promise<SendMessageResponse>;
+/** Ask the service to abandon the assistant reply it is generating for
+ *  `userMessageId` — the "stop" a chat surface puts beside a reply in progress.
+ *
+ *  Addressed by USER message, not by conversation: the thing being abandoned is
+ *  one turn, and the id comes from that turn's own send response
+ *  (`userMessageIdOf`). There is no route that looks it up afterwards, so a
+ *  caller that did not keep it cannot abort.
+ *
+ *  Resolving means the service ACCEPTED the abort, not that generation had not
+ *  already finished — a reply that was already written still lands in the
+ *  transcript. Rejecting means the turn is still running: treat it as "could
+ *  not stop", never as "stopped". */
+export declare function abortAssistantMessageGeneration(userMessageId: string): Promise<AbortAssistantMessageGenerationResponse>;
 /** Fetch the messages of a conversation (poll after sendMessage). */
 export declare function getConversationMessages(conversationId: string): Promise<GetConversationMessagesResponse>;
 /** The transcript from a getConversationMessages response, under either key. */
 export declare function messagesOf(res: GetConversationMessagesResponse | null | undefined): ConversationMessage[];
+/** The id of the user turn a send response stored, or "" when the service did
+ *  not name one. Empty is a real answer, not a parse failure: it means this turn
+ *  cannot be aborted, and a caller must degrade rather than send `undefined` to
+ *  the abort route. */
+export declare function userMessageIdOf(res: SendMessageResponse | null | undefined): string;
 /** The conversation id from a createConversation response, under either key. */
 export declare function conversationIdOf(res: CreateConversationResponse | null | undefined): string;
 /** A message's text. `content` is normally a string, but can arrive as an object

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/wix-genie-chat.mjs

@@ -56,7 +56,19 @@ function sendMessage(conversationId, content, modeOrOptions = "POLLING") {
         "@himalaya/wix-genie-chat: conversation-user-message returned no userMessage.id, so the agent would have no turn to answer"
       );
     }
-    return triggerAssistantMessage(conversationId, userMessageId, opts).catch((cause) => {
+    return triggerAssistantMessage(conversationId, userMessageId, opts).then((res) => ({
+      ...res,
+      // The id the turn was STORED under, carried out on the response.
+      //
+      // It only exists on step 1's reply, which callers never see, and there is
+      // no route that looks it up afterwards — so a caller that wants to abort
+      // this turn later has exactly one chance to learn it, here. Before the
+      // send became two calls it could be read off this very response
+      // (`userMessage.id`); it cannot now, and a caller doing that silently got
+      // `""` — which reads as "nothing to abort" rather than as an error, so the
+      // Stop control would simply never appear. Hence carrying it explicitly.
+      userMessageId
+    })).catch((cause) => {
       const e = genieChatError(
         "request",
         `@himalaya/wix-genie-chat: the turn was stored but the agent could not be triggered: ${String(cause?.message ?? cause)}`,
@@ -81,6 +93,10 @@ function triggerAssistantMessage(conversationId, userMessageId, opts = {}) {
     ...opts.enforceAccountScopedConversations === void 0 ? {} : { enforceAccountScopedConversations: opts.enforceAccountScopedConversations }
   });
 }
+function abortAssistantMessageGeneration(userMessageId) {
+  if (!userMessageId) throw new Error("abortAssistantMessageGeneration: userMessageId is required");
+  return wixCall("POST", `${BASE}/abort-assistant-message-generation`, { userMessageId });
+}
 function getConversationMessages(conversationId) {
   if (!conversationId) throw new Error("getConversationMessages: conversationId is required");
   return wixCall("GET", `${BASE}/conversation-messages?conversationId=${encodeURIComponent(conversationId)}`);
@@ -88,6 +104,9 @@ function getConversationMessages(conversationId) {
 function messagesOf(res) {
   return res?.messages ?? res?.conversationMessages ?? [];
 }
+function userMessageIdOf(res) {
+  return (res?.userMessageId ?? res?.userMessage?.id ?? "").trim();
+}
 function conversationIdOf(res) {
   return (res?.conversationId || res?.conversation?.id || "").trim();
 }
@@ -114,6 +133,7 @@ function lastAssistantMessage(msgs) {
 export {
   ARIA_ORIGIN,
   ARIA_UNIFIED_ASSISTANT_ID,
+  abortAssistantMessageGeneration,
   ariaAssistantConfig,
   conversationIdOf,
   conversationUserMessage,
@@ -127,6 +147,7 @@ export {
   messagesOf,
   sendMessage,
   triggerAssistantMessage,
+  userMessageIdOf,
   wixCall
 };
 //# sourceMappingURL=wix-genie-chat.mjs.map

package/guides/sdk-reference.json

@@ -16721,7 +16721,13 @@
         "name": "SendMessageResponse",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface SendMessageResponse { assistantMessages?: ConversationMessage[]; conversationMessage?: ConversationMessage }"
+        "decl": "export interface SendMessageResponse {\n  assistantMessages?: ConversationMessage[];\n  conversationMessage?: ConversationMessage;\n  /** The user's own turn AS STORED by the service — present on step 1's reply\n   *  (`conversationUserMessage`), which is where the id actually comes from. */\n  userMessage?: ConversationMessage;\n  /** The id the owner's turn was stored under, carried out by `sendMessage`.\n   *\n   *  The only handle the abort route accepts, and there is no route that looks\n   *  it up afterwards — so a caller that wants to stop the reply has to keep it\n   *  from the send. `sendMessage` resolves with step 2's response, which does\n   *  NOT carry `userMessage`, so this field is the one reliable source; read it\n   *  through `userMessageIdOf` rather than directly. */\n  userMessageId?: string;\n}"
+      },
+      {
+        "name": "AbortAssistantMessageGenerationResponse",
+        "kind": "type",
+        "jsdoc": "/** Empty on success — the service answers `{}`. Named rather than `void` so a\n *  future field has somewhere to land without changing every call site. */",
+        "decl": "export type AbortAssistantMessageGenerationResponse = Record<string, never>;"
       },
       {
         "name": "GetConversationMessagesResponse",
@@ -16777,6 +16783,12 @@
         "jsdoc": "/** Step 2 of sending a turn on its own: ask the agent to answer a user message\n *  that `conversationUserMessage` has ALREADY stored.\n *\n *  Exported because it is the only safe retry when step 2 is the half that\n *  failed — see `sendMessage`, which attaches the id to its error for exactly\n *  this call. Carries no content: the turn it names is the content. */",
         "decl": "export function triggerAssistantMessage(\n  conversationId: string,\n  userMessageId: string,\n  opts: SendMessageOptions = {},\n): Promise<SendMessageResponse>;"
       },
+      {
+        "name": "abortAssistantMessageGeneration",
+        "kind": "function",
+        "jsdoc": "/** Ask the service to abandon the assistant reply it is generating for\n *  `userMessageId` — the \"stop\" a chat surface puts beside a reply in progress.\n *\n *  Addressed by USER message, not by conversation: the thing being abandoned is\n *  one turn, and the id comes from that turn's own send response\n *  (`userMessageIdOf`). There is no route that looks it up afterwards, so a\n *  caller that did not keep it cannot abort.\n *\n *  Resolving means the service ACCEPTED the abort, not that generation had not\n *  already finished — a reply that was already written still lands in the\n *  transcript. Rejecting means the turn is still running: treat it as \"could\n *  not stop\", never as \"stopped\". */",
+        "decl": "export function abortAssistantMessageGeneration(userMessageId: string): Promise<AbortAssistantMessageGenerationResponse>;"
+      },
       {
         "name": "getConversationMessages",
         "kind": "function",
@@ -16789,6 +16801,12 @@
         "jsdoc": "/** The transcript from a getConversationMessages response, under either key. */",
         "decl": "export function messagesOf(res: GetConversationMessagesResponse | null | undefined): ConversationMessage[];"
       },
+      {
+        "name": "userMessageIdOf",
+        "kind": "function",
+        "jsdoc": "/** The id of the user turn a send response stored, or \"\" when the service did\n *  not name one. Empty is a real answer, not a parse failure: it means this turn\n *  cannot be aborted, and a caller must degrade rather than send `undefined` to\n *  the abort route. */",
+        "decl": "export function userMessageIdOf(res: SendMessageResponse | null | undefined): string;"
+      },
       {
         "name": "conversationIdOf",
         "kind": "function",

package/guides/tier-5-add-a-screen.md

@@ -891,6 +891,119 @@ Branch in the action body. Server tells the client which segment via descriptor
 
 ---
 
+## A reducer must return a WHOLE state, never a patch
+
+A worker action returns the **entire** next state, not the fields it changed:
+
+```ts
+// WRONG — reads as "I only changed status", and on some hosts means
+// "I deleted everything else"
+stop: async (s) => {
+  await abort(s.jobId);
+  return { status: "ready" };
+}
+
+// RIGHT
+stop: async (s) => {
+  await abort(s.jobId);
+  return { ...s, status: "ready" };
+}
+```
+
+**Why this is worth its own section.** The hosts do not agree about what a
+returned record means. One merges it onto the state it already holds, so the
+wrong version above looks perfectly fine; another assigns it, so the same code
+silently drops every field you left out. A partial return therefore passes on
+the surface you tested and loses data on the one you did not — with no error, no
+warning, and nothing in the log. "Return only what you changed" is the normal
+instinct, and it is the one this platform punishes.
+
+**When an action awaits, it holds a stale snapshot.** Spreading `s` after an
+`await` writes back the values as they were *before* it, so anything that
+changed meanwhile is overwritten. There are two different problems in that
+sentence, and they need two different answers.
+
+### Should this result be committed at all?
+
+If the await crossed a point where the *whole* state moved on — the person
+started a new item, cancelled the one in flight, reset the screen — then nothing
+this action computed is worth keeping. Do not merge a repaired version of it;
+stand down by returning **`undefined`**, so the newer state stands and the next
+action reconciles.
+
+**`undefined`, and nothing else.** Not `null`, not `false`, not `{}`. Only
+`undefined` is read as "I have no opinion" everywhere; the other falsy values
+are read as a *state* by at least one host and will replace the service's
+state with them, taking every binding down with it. One host is lenient about
+this and another is not, so the wrong spelling is a bug that passes wherever you
+happen to test it:
+
+```ts
+// Module scope, beside the service: a latch, not state. It must not be
+// persisted, and reducers cannot see each other's locals any other way.
+let turnSeq = 0;                        // bumped by EVERY action that starts,
+                                        // cancels or replaces the unit of work
+
+defineService("feed", {
+  state: { data: [], status: "ready" },
+  actions: {
+    start: async (s) => { turnSeq += 1; return { ...s, status: "loading" }; },
+
+    refresh: async (s) => {
+      const seq = turnSeq;              // read BEFORE the await
+      const data = await load();
+      // A boundary moved while we were reading: `s` predates it, and returning
+      // anything built from `s` would undo whatever moved it.
+      if (turnSeq !== seq) return undefined;
+      return { ...s, data };
+    },
+  },
+});
+```
+
+Put that check **before every return in the block, including the error path** —
+a read that threw is exactly as stale as one that succeeded, and `return s` in a
+`catch` is just as much a stale write.
+
+### Or committed, but with one field kept current?
+
+If the await crossed an *ordinary* edit instead — typing into a field, say —
+the result is still wanted; only that one field must not be rolled back. Carry
+it across explicitly, and only when it actually moved:
+
+```ts
+let draft = "";
+let draftSeq = 0;                       // bumped by the action that owns it
+
+defineService("composer", {
+  state: { input: "", status: "ready" },
+  actions: {
+    onType: (s, v) => {
+      draft = v;
+      draftSeq += 1;
+      return { ...s, input: v };
+    },
+
+    confirm: async (s) => {
+      const typedAt = draftSeq;         // read BEFORE the await
+      await somethingSlow();
+      const next = { ...s, status: "ready" };
+      // Only re-apply a draft typed DURING the await.
+      return draftSeq === typedAt ? next : { ...next, input: draft };
+    },
+  },
+});
+```
+
+The counter is what keeps this honest. Re-applying whenever the latch merely
+*differs* from the snapshot resurrects a value the action legitimately cleared —
+a submit that empties the box, followed by a slow confirm, puts the submitted
+text straight back into it.
+
+**The two are not alternatives.** An action that awaits usually needs both: the
+boundary check to decide whether to commit, and the carry-across for the fields
+an ordinary edit may have moved underneath it.
+
 ## Anti-patterns
 
 Don't use Tier 5 for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.940.0",
+  "version": "0.942.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "9cbb37281f079a04b648edee13a6f4aad84789cd285a2a200c8e6a55"
+  "falconPackageHash": "8700bed97461c826fd04a33c50c3cc26d349fdeaad788594d2f598c1"
 }

package/templates/beauty-salon-owner/dev/index.ts

@@ -55035,6 +55035,63 @@ const SCREENS = runtimeSetting({
                 }
               }
             },
+            {
+              "id": "himi_owner_lite_aria.stop",
+              "body": {
+                "package": "himalaya",
+                "type": "HStack",
+                "props": {
+                  "spacing": 6,
+                  "children": [
+                    {
+                      "id": "",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Spacer",
+                        "props": {}
+                      }
+                    },
+                    {
+                      "id": "",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Icon",
+                        "props": {
+                          "name": "close",
+                          "size": 14,
+                          "tint": "accentPrimary"
+                        }
+                      }
+                    },
+                    {
+                      "id": "",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "Stop",
+                          "style": "footnote",
+                          "color": "accentPrimary",
+                          "maxLines": 1
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "modifiers": {
+                "padding": {
+                  "leading": 0,
+                  "trailing": 0,
+                  "top": 4,
+                  "bottom": 0
+                },
+                "onTap": {
+                  "actionId": "tier5.himiOwnerLiteAria.stop"
+                },
+                "hiddenPath": "$service:himiOwnerLiteAria.stopHidden"
+              }
+            },
             {
               "id": "",
               "body": {