@wix/himalaya-cli 0.1014.0 → 0.1016.0

package/templates/gym-fitness-owner/tier5-src/_shared/aria-chat.ts

@@ -31,16 +31,20 @@ import {
   ariaAssistantConfig,
   conversationIdOf,
   createConversation,
+  functionCallsOf,
   getConversationMessages,
   getConversations,
   messageText,
   messagesOf,
+  sendFunctionCallResults,
   sendMessage,
   triggerAssistantMessage,
   userMessageIdOf,
   type ConversationMessage,
   type ConversationSummary,
+  type SendMessageResponse,
 } from "@himalaya/wix-genie-chat";
+import { runClientToolExchange, type AriaClientTools } from "./aria-client-tools.js";
 import { proseOfParts, scanEnvelopes, stripHidden } from "./aria-widgets.js";
 import { isWebUrl, stripMarkdown } from "./aria-widget-model.js";
 import { NO_WIDGET, activeWidgetOf, asyncAdvanced, type SubtreeSlot, type WidgetOptionRow, type WidgetView }
@@ -61,6 +65,11 @@ import { LOCAL_ID_PREFIX, createRowMemo, mintLocalId, transcriptKeys, type RowMe
  *  so both sides import this. */
 export const ARIA_LINK_SLOTS = 3;
 
+/** The longest consent question put in front of the owner. It is model output
+ *  shown in a modal, so an agent that writes an essay must not be able to push
+ *  the buttons off a small screen. */
+export const CONSENT_MAX_CHARS = 600;
+
 /** One rendered message. Every bubble carries ALL link slots — a `$item.` path
  *  that is missing on some rows does not substitute, so the fields are always
  *  present and `linkNHidden` collapses the unused ones. */
@@ -232,6 +241,10 @@ export interface AriaChatLabels {
    *  all — it carries no Wix app binding to sign the chat-service call with.
    *  See `isWixAccountUnreachable`, and note what it is NOT: a signed-out user. */
   unavailable?: Resolvable<string>;
+  /** Shown when a client-tool exchange broke down (see `clientTools`) and the
+   *  turn cannot finish. The underlying reason is a protocol fault the owner can
+   *  do nothing about, so it is not what they are shown. */
+  toolFailed?: Resolvable<string>;
 }
 
 export interface AriaChatOptions {
@@ -248,6 +261,15 @@ export interface AriaChatOptions {
    *  it renders an ASYNC_TOOL's opening message and never advances it, which is
    *  strictly better than showing a spinner that can never stop. */
   asyncJobState?: (jobId: string) => Promise<string>;
+  /** Run the client tools the agent asks for — above all, ask the OWNER before
+   *  it acts on their account (`aria-client-tools.ts` says why that is a security
+   *  boundary and what "asking" must and must not mean).
+   *
+   *  Optional, and omitting it is safe: every call is then answered "not found",
+   *  which unblocks the agent without anyone having agreed to anything. What is
+   *  NOT safe is leaving a call unanswered — the agent waits for the result, so
+   *  the turn would never end. */
+  clientTools?: AriaClientTools;
   greeting: Resolvable<string>;
   prompts: Resolvable<AriaPromptChip[]>;
   labels?: AriaChatLabels;
@@ -588,6 +610,16 @@ export function toBubbles(
   return out;
 }
 
+/** What of an assistant row a READER should see: HIDDEN notes out first (the
+ *  service's own, transcript-only), then widget envelopes, leaving the prose.
+ *  One function because two readers need it — the bubble and the consent
+ *  question — and a cleaning stage added to one and not the other is raw markup
+ *  in front of the owner. `closed` is false for a row still being written, whose
+ *  trailing unterminated envelope must stay hidden. */
+export function assistantProse(raw: string, closed = true): string {
+  return proseOfParts(scanEnvelopes(stripHidden(raw), 0, closed).parts);
+}
+
 /** Bubbles are built from one message's raw text; `null` is "paints nothing". */
 export type BubbleMemo = RowMemo<AriaBubble | null>;
 export const createBubbleMemo = (): BubbleMemo => createRowMemo<AriaBubble | null>();
@@ -602,7 +634,7 @@ function bubbleOf(id: string, role: string, who: string, raw: string, writing: b
   // A row the service is still writing is scanned as STREAMING: an
   // envelope whose `>>` has not arrived yet is held back rather than
   // painted as raw JSON until the row finishes.
-  const prose = role === "USER" ? raw : proseOfParts(scanEnvelopes(stripHidden(raw), 0, !writing).parts);
+  const prose = role === "USER" ? raw : assistantProse(raw, !writing);
   const content = role === "USER" ? prose : stripMarkdown(prose);
   if (!content || !content.trim()) return null;
   return {
@@ -1037,6 +1069,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const unavailableText = () => res(
     o.labels?.unavailable ?? `${assistant()} can't reach your Wix account from here.`,
   );
+  const toolFailedText = () => res(o.labels?.toolFailed ?? `${assistant()} couldn't finish that. Try again.`);
   const promptList = () => res(o.prompts);
   const siteOf = o.siteId ?? (() => "");
   const resumeOf = o.resumeConversationId ?? inputConversationId;
@@ -1181,6 +1214,164 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   let draft = "";
   let draftSeq = 0;
 
+  /** The client-tool exchange the current turn is in the middle of, if any.
+   *
+   *  While it runs, the agent is WAITING ON US — for the owner's consent, say —
+   *  so the turn is still in flight whatever the transcript shows, and nothing
+   *  may read it as over: not a note the agent wrote before asking, not a count
+   *  that happens to have moved. `tick` and `busyLoop` both hold the turn open on
+   *  this.
+   *
+   *  A latch rather than state for the reason `inFlightSend` is one: the exchange
+   *  outlives the action that started it (see `startToolExchange`), so no state
+   *  that action returned can describe it. Keyed by conversation and turn epoch,
+   *  so it only ever holds the turn it belongs to. */
+  let toolExchange: { convId: string; seq: number; done: Promise<void> } | null = null;
+  /** The reply the owner is owed once an exchange has been answered: the
+   *  assistant row the last results post opened. Until it is written, an
+   *  earlier row — a note the agent wrote before asking — must not read as the
+   *  turn's answer; it predates the owner's consent. */
+  let toolAnswer: { convId: string; seq: number; messageId: string } | null = null;
+  /** What the transcript held just before this turn's LAST results post: the
+   *  assistant rows that already existed, and how many of them were finished
+   *  answers (`null` when that read failed). Every one of those predates the
+   *  owner's consent, so none can be the reply to it.
+   *
+   *  The fallback for when the results post names no row (`toolAnswer` unset)
+   *  or names one the transcript does not hold. Without it the ordinary rule
+   *  runs, and it reads a note the agent wrote BEFORE asking as the answer:
+   *  typing and Stop clear while the approved operation is still running, and
+   *  a second turn can start on top of it. */
+  let toolPosted: { convId: string; seq: number; ids: Set<string>; settled: number | null } | null = null;
+  /** An exchange that FAILED, waiting for the next transcript read to end its
+   *  turn. Same keying: a failure is only ever reported against its own turn. */
+  let toolFailure: { convId: string; seq: number; error: unknown } | null = null;
+
+  const exchanging = (convId: string): boolean =>
+    !!toolExchange && toolExchange.convId === convId && toolExchange.seq === turnSeq;
+
+  /** Has the reply owed after an exchange landed? `null` when this turn had no
+   *  exchange, so the ordinary rule decides.
+   *
+   *  The row the last results post opened decides when the transcript holds
+   *  it. Otherwise — no row named, or the service stored the reply under
+   *  another id — the answer is a finished assistant row that was NOT there
+   *  before the post (`toolPosted`), never one that was. */
+  const toolReplied = (convId: string, msgs: ConversationMessage[]): boolean | null => {
+    const a = toolAnswer;
+    if (a && a.convId === convId && a.seq === turnSeq) {
+      const row = msgs.find((m) => m.id === a.messageId);
+      if (row) return !!answerText(row) && !stillWriting(row);
+    }
+    const p = toolPosted;
+    if (!p || p.convId !== convId || p.seq !== turnSeq) return null;
+    let unkeyed = false;
+    for (const m of msgs) {
+      if ((m.role || "ASSISTANT") !== "ASSISTANT") continue;
+      if (!m.id) { unkeyed = true; continue; }
+      if (!p.ids.has(m.id) && answerText(m) && !stillWriting(m)) return true;
+    }
+    // Rows without an id cannot be told apart, so only a count can say one is
+    // new — and only when the count before the post was read.
+    return unkeyed && p.settled !== null ? countSettledAnswers(msgs) > p.settled : false;
+  };
+
+  /** The assistant rows in the transcript right now — `toolPosted`'s input.
+   *  Never rejects: a failed read is reported as `null`. */
+  const assistantRowsNow = async (convId: string): Promise<{ ids: string[]; settled: number } | null> => {
+    try {
+      const raw = messagesOf(await getConversationMessages(convId));
+      const ids = raw.filter((m) => (m.role || "ASSISTANT") === "ASSISTANT" && m.id).map((m) => m.id as string);
+      return { ids, settled: countSettledAnswers(raw) };
+    } catch {
+      return null;
+    }
+  };
+
+  /** The failure of THIS conversation's current turn, consumed on read. */
+  const takeToolFailure = (convId: string): unknown => {
+    const f = toolFailure;
+    if (!f || f.convId !== convId || f.seq !== turnSeq) return null;
+    toolFailure = null;
+    return f.error ?? new Error("client tools failed");
+  };
+
+  /** How a broken exchange reads on screen. The Wix-unreachable refusals keep
+   *  their own neutral sentence; anything else is a protocol fault the owner can
+   *  do nothing about, so they get a plain one rather than its text. */
+  const toolFailureSlots = (e: unknown): { error: string; statusText: string } =>
+    isWixAccountUnreachable(e) ? failureSlots(e, unavailableText) : { error: toolFailedText(), statusText: "" };
+
+  /** The agent's consent question as the owner should read it: its envelopes,
+   *  HIDDEN notes and markdown gone — the same stages a bubble goes through — and
+   *  capped, because it is model output and lands in a modal. */
+  const consentBody = (raw: string): string => {
+    const prose = stripMarkdown(assistantProse(raw)).trim();
+    // Cut by code POINT, not UTF-16 unit, so an emoji at the boundary is never
+    // split into a lone surrogate.
+    const chars = Array.from(prose);
+    return chars.length > CONSENT_MAX_CHARS ? `${chars.slice(0, CONSENT_MAX_CHARS - 1).join("").trimEnd()}…` : prose;
+  };
+
+  /** The host's tools, with the question cleaned on its way to the owner. */
+  const toolHost = (): AriaClientTools | undefined => {
+    const t = o.clientTools;
+    if (!t) return undefined;
+    return { confirm: (ask) => t.confirm({ message: consentBody(ask.message) }), userAgent: t.userAgent };
+  };
+
+  /** Answer the client tools a send's response asked for, WITHOUT holding the
+   *  send open.
+   *
+   *  Detached on purpose. On the `_poll` path the owner's own bubble and the
+   *  typing line paint when `send` RETURNS — so awaiting a consent inside it would
+   *  put the question on screen over a chat that does not yet show what the owner
+   *  asked. Instead the send commits, the ladder runs, and the exchange holds the
+   *  turn open (`exchanging`) until it is done.
+   *
+   *  The consent presenter is modal, so nothing on the Aria screen — Stop, ➕,
+   *  the composer — can be reached while the owner is being asked. The epoch
+   *  check still guards the result: if the turn has moved on regardless, the
+   *  answer is not sent (`runClientToolExchange`, "abandoned"). */
+  function startToolExchange(convId: string, first: SendMessageResponse): void {
+    if (!functionCallsOf(first).length) return;
+    const seq = turnSeq;
+    const current = () => turnSeq === seq;
+    const mine: { convId: string; seq: number; done: Promise<void> } = { convId, seq, done: Promise.resolve() };
+    toolExchange = mine;
+    // Rows the service handed back while it was still ASKING are notes written
+    // before the owner answered. Kept even when the pre-post read fails, which
+    // is when they are the only record of what predates the result.
+    const asked = new Set<string>();
+    const noteRows = (res: SendMessageResponse) => {
+      for (const r of res.assistantMessages ?? []) if (r.id) asked.add(r.id);
+    };
+    noteRows(first);
+    mine.done = runClientToolExchange(first, {
+      host: toolHost(),
+      callsOf: functionCallsOf,
+      beforeSend: async () => {
+        const now = await assistantRowsNow(convId);
+        if (!current()) return;
+        toolPosted = { convId, seq, ids: new Set([...asked, ...(now?.ids ?? [])]), settled: now ? now.settled : null };
+      },
+      send: async (results) => {
+        const res = await sendFunctionCallResults(convId, results, { origin });
+        if (functionCallsOf(res).length) noteRows(res);
+        return res;
+      },
+      stillCurrent: current,
+      onFinal: (res) => {
+        const rows = res.assistantMessages ?? [];
+        const id = rows[rows.length - 1]?.id;
+        if (id && current()) toolAnswer = { convId, seq, messageId: id };
+      },
+    }).then(
+      () => undefined,
+      (error: unknown) => { if (current()) toolFailure = { convId, seq, error }; },
+    ).then(() => { if (toolExchange === mine) toolExchange = null; });
+  }
+
   /** Raise the fence for one abort of `seq`; returns the lowering half. */
   const fenceEpoch = (seq: number): (() => void) => {
     abortingEpochs.set(seq, (abortingEpochs.get(seq) ?? 0) + 1);
@@ -1301,11 +1492,20 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       const bubbles = toBubbles(raw, assistant(), you(), bubbleMemo);
       if (bubbles.length) server = bubbles;
       seen = raw;
+      const failed = takeToolFailure(convId);
+      if (failed) {
+        return { ...s, status: "ready", _convId: convId, messages: server, input: "", _pending: "", _abortId: "", ...observed(raw, s.widget), ok: false, ...toolFailureSlots(failed) };
+      }
+      // Not over while the agent is waiting on a client tool from us — and this
+      // loop has no clock of its own, so re-reading meanwhile would spend its
+      // rounds in a burst. Wait for the exchange, then read again.
+      const pendingExchange = exchanging(convId) ? toolExchange : null;
+      if (pendingExchange) { await pendingExchange.done; n--; continue; }
       // The turn is over when the SERVER holds an assistant answer — which a
       // widget-only reply is, even though it leaves no bubble to inspect. Asking
       // the last BUBBLE stalled this loop on exactly that reply, the same way it
       // stalled `tick`.
-      if (repliedTo(raw, s._turnId) ?? countSettledAnswers(raw) > s._replyAfter) {
+      if (toolReplied(convId, raw) ?? repliedTo(raw, s._turnId) ?? countSettledAnswers(raw) > s._replyAfter) {
         return { ...s, status: "ready", _convId: convId, messages: bubbles, prompts: [], input: "", statusText: "", error: "", _pending: "", ...observed(raw, s.widget), ok: false };
       }
     }
@@ -1452,13 +1652,19 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // The retry path needs no send to learn it: holding that id is what
       // `stalledTurn` IS. So a turn recovered from a failed trigger is just as
       // stoppable as one sent cleanly.
+      //
+      // The response is kept, not just its id: it is also where the agent asks
+      // for client tools (`startToolExchange`), on the retry path as much as on
+      // a clean send.
       let abortId: string;
+      let answer: SendMessageResponse;
       if (stalled) {
         retriedId = stalled.userMessageId;
         abortId = stalled.userMessageId;
-        await triggerAssistantMessage(convId, stalled.userMessageId, { origin });
+        answer = await triggerAssistantMessage(convId, stalled.userMessageId, { origin });
       } else {
-        abortId = userMessageIdOf(await sendMessage(convId, content, { origin }));
+        answer = await sendMessage(convId, content, { origin });
+        abortId = userMessageIdOf(answer);
       }
       // A SECOND boundary bump, and the load-bearing one. The bump at entry only
       // retires a tick that was already parked when the owner tapped Send. A tick
@@ -1513,6 +1719,8 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // the answer to this one.
       const sent: AriaChatState = { ...marked, _abortId: abortId, _turnId: abortId };
       inFlightSend = null;
+      // After the second bump, so the exchange is keyed to THIS turn's epoch.
+      startToolExchange(convId, answer);
       if (o.poll) {
         // Return NOW. The host owns the clock from here; `tick` merges the
         // reply in when it lands.
@@ -1935,22 +2143,31 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // Counted over RAW messages, so a widget-only answer still ends the turn
         // instead of pinning the ladder to its fast rung forever (`countTurns`).
         // Exact when the service named the turn, counted when it did not.
-        const replied = repliedTo(raw, s._turnId) ?? countSettledAnswers(raw) > s._replyAfter;
+        //
+        // …and never while the agent is waiting on a client tool from us: it has
+        // asked, say, for the owner's consent and will write nothing more until it
+        // has the answer, so whatever the transcript shows the turn is still ours
+        // to finish. An exchange that FAILED ends it instead, with a line saying so.
+        const failed = takeToolFailure(s._convId);
+        const replied = !failed && !exchanging(s._convId)
+          && (toolReplied(s._convId, raw) ?? repliedTo(raw, s._turnId) ?? countSettledAnswers(raw) > s._replyAfter);
+        const ended = replied || !!failed;
         const next: AriaChatState = {
           ...s,
-          status: replied ? "ready" : s.status,
+          status: ended ? "ready" : s.status,
           messages: painted,
-          _pending: pending,
+          _pending: failed ? "" : pending,
           ...observed(raw, s.widget),
           prompts: promptsFor(painted, promptList()),
-          statusText: replied ? "" : s.statusText,
+          statusText: ended ? "" : s.statusText,
+          ...(failed ? { _abortId: "", ...toolFailureSlots(failed) } : {}),
         };
         // The async job rides this same tick — see `withJobProgress`. Done
         // AFTER the transcript rebuild, so a widget that has just been retired
         // by a new answer is never polled for.
         const withJob = { ...next, widget: await withJobProgress(next.widget) };
         // Slow the ladder the moment the turn is over; leave it alone otherwise.
-        return replied && wasFast ? cadence(withJob, o.poll.idleMs, o.poll.fastMs) : withJob;
+        return ended && wasFast ? cadence(withJob, o.poll.idleMs, o.poll.fastMs) : withJob;
       } catch {
         // A read that THREW is exactly as stale as one that resolved: if a turn
         // boundary moved on while it was in flight, returning `s` merges the

package/templates/gym-fitness-owner/tier5-src/_shared/aria-client-tools.ts

@@ -0,0 +1,234 @@
+// Client tools for the Wix "Aria" assistant: the calls the agent makes on the
+// CLIENT, and the consent gate in front of the one that matters.
+//
+// The chat-service can answer a turn with `functionCalls` instead of an assistant
+// message. The agent is then blocked: it writes nothing more until the client
+// sends a result back (`sendFunctionCallResults`), and a client that ignores the
+// call leaves "Aria is typing…" on screen for good. So every call gets an answer
+// — even one this client cannot run, which is answered "not found" in the exact
+// words the service already reads from the other two clients.
+//
+// Two built-ins exist, both taken from the native Aria app and the React Native
+// dashboard assistant, which agree on them to the letter:
+//
+//  - `consentWithMessage` — "may I do this?". The agent asks BEFORE acting on the
+//    owner's account (sending a campaign, changing a product), and the owner's
+//    answer goes back as `userConsent`. THIS IS A SECURITY BOUNDARY, not a
+//    feature: the text of the question is model output, and the model's input
+//    includes content the owner does not control (a review, an enquiry, a product
+//    description) — so a prompt-injected agent can ask for anything. The answer
+//    is the only thing standing between that and the account. Hence:
+//      * approval needs an explicit tap. Anything else — a dismissal, a host with
+//        nothing to ask with, a presenter that threw — is NOT consent; the first
+//        is answered as a refusal and the others as a failure, never as a yes.
+//      * NO remembered consent. The native app can auto-approve a `consentKey`
+//        it has seen approved in the same conversation. That is a convenience,
+//        and one that turns a single yes into a standing grant the agent can
+//        re-use on a different action under the same key. It has to be argued for
+//        on its own; it is not inherited here.
+//      * the BUTTONS are ours. The agent may suggest `approveText`/`denyText`, and
+//        they are ignored: an approve button labelled "Cancel" is how a model that
+//        cannot forge the tap gets the owner to make it.
+//  - `getClientSideKnowledge` — "what are you running on?". Read-only; answered
+//    with a user-agent string and the call's own arguments echoed back.
+//
+// This file is copied verbatim into every generated starter app, so it explains
+// itself without pointing at anything only this repo has.
+
+// Types only: this module has no runtime dependency, so it can be unit-tested
+// without a bundler. The one decoder it needs is handed in (`callsOf`).
+import type { FunctionCall, FunctionCallResult, SendMessageResponse } from "@himalaya/wix-genie-chat";
+
+/** A service that keeps asking is a loop, not a conversation. Ten is the cap
+ *  both native clients use: ten results sent, and an eleventh call fails the
+ *  turn rather than being answered. */
+export const CLIENT_TOOL_MAX_ROUNDS = 10;
+
+export const CONSENT_TOOL = "consentWithMessage";
+export const KNOWLEDGE_TOOL = "getClientSideKnowledge";
+
+/** A function call with its arguments decoded. */
+export interface ClientToolCall {
+  id?: string;
+  name?: string;
+  /** Which tool this is: `toolSequence.currentStep` when the call is a step of a
+   *  sequence, otherwise its name. */
+  toolId: string;
+  /** Every argument EXCEPT `toolSequence`, which is routing, not payload. */
+  params: Record<string, unknown>;
+}
+
+/** What the host must provide to run the built-ins. Omit it and every call is
+ *  answered "not found" — honest, and it unblocks the agent. */
+export interface AriaClientTools {
+  /** Ask the owner whether the agent may go ahead, and resolve with the answer.
+   *
+   *  Resolve `true` ONLY for an explicit approval. A dismissal is a refusal. A
+   *  rejection (nothing to present with, a presenter already busy) is reported to
+   *  the agent as a failure — it is never read as consent.
+   *
+   *  `message` is the agent's question, already reduced to plain text. It can be
+   *  empty; the host supplies its own fallback. */
+  confirm: (ask: { message: string }) => Promise<boolean>;
+  /** Reported by `getClientSideKnowledge`. */
+  userAgent?: () => string;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Decode a call's `arguments`, or `null` when they are not a JSON object.
+ *
+ *  `arguments` is a JSON-ENCODED string on the wire. An object is accepted too,
+ *  in case a gateway ever decodes it on the way through; anything else — an
+ *  array, a number, malformed text — is not a call this client can run, and the
+ *  caller answers it as a failure rather than guessing. */
+export function parseClientToolCall(call: FunctionCall): ClientToolCall | null {
+  // The service's array is not ours to trust element by element: a `null` in it
+  // must be answered, not thrown on.
+  if (!call || typeof call !== "object" || Array.isArray(call)) return null;
+  const raw = (call as { arguments?: unknown }).arguments;
+  let args: unknown;
+  if (raw === undefined || raw === null || raw === "") args = {};
+  else if (typeof raw === "string") {
+    try { args = JSON.parse(raw); } catch { return null; }
+  } else args = raw;
+  if (!isPlainObject(args)) return null;
+  const { toolSequence, ...params } = args;
+  let sequence: unknown = toolSequence;
+  if (typeof sequence === "string") {
+    try { sequence = JSON.parse(sequence); } catch { sequence = undefined; }
+  }
+  const step = isPlainObject(sequence) && typeof sequence.currentStep === "string" ? sequence.currentStep : "";
+  return { id: call.id, name: call.name, toolId: step || call.name || "", params };
+}
+
+/** `{id, name}` copied from the call, omitting what the call did not carry. */
+function addressOf(call: { id?: string; name?: string }): FunctionCallResult {
+  return {
+    ...(call.id === undefined ? {} : { id: call.id }),
+    ...(call.name === undefined ? {} : { name: call.name }),
+  };
+}
+
+/** The literal text the service already reads from the other clients. */
+export function notFoundResult(call: ClientToolCall): FunctionCallResult {
+  return { ...addressOf(call), success: false, content: `tool '${call.name || call.toolId}' not found and cannot be executed` };
+}
+
+export function failedResult(call: { id?: string; name?: string }, message: string): FunctionCallResult {
+  return { ...addressOf(call), success: false, content: `tool '${call.name ?? ""}' execution failed: ${message}` };
+}
+
+/** The owner's answer. A refusal is still a SUCCESSFUL tool run — the tool's job
+ *  was to ask, and it did; the model replies to the refusal. */
+export function consentResult(call: ClientToolCall, approved: boolean): FunctionCallResult {
+  return { ...addressOf(call), success: true, widgetResponse: JSON.stringify({ ...call.params, userConsent: approved }) };
+}
+
+export function knowledgeResult(call: ClientToolCall, userAgent: string): FunctionCallResult {
+  return { ...addressOf(call), success: true, content: "", widgetResponse: JSON.stringify({ ...call.params, userAgent }) };
+}
+
+/** Answer ONE call. Never rejects: every outcome, including a host that threw,
+ *  becomes a result the agent can read, because an unanswered call is a turn
+ *  that never ends. */
+export async function answerClientTool(call: FunctionCall, host: AriaClientTools | undefined): Promise<FunctionCallResult> {
+  const parsed = parseClientToolCall(call);
+  if (!parsed) return failedResult(call && typeof call === "object" ? call : {}, "arguments are not a JSON object");
+  if (!host) return notFoundResult(parsed);
+  if (parsed.toolId === CONSENT_TOOL) {
+    const message = typeof parsed.params.message === "string" ? parsed.params.message : "";
+    let approved: boolean;
+    try {
+      // Strictly `true`. A host that resolves with something truthy but not
+      // `true` — a `{confirmed:false}` object passed straight through, the string
+      // "false" — has not reported an approval, and reading it as one would be
+      // the single worst bug this file could have.
+      approved = (await host.confirm({ message })) === true;
+    } catch (e) {
+      return failedResult(parsed, `the owner could not be asked (${String((e as Error)?.message ?? e)})`);
+    }
+    return consentResult(parsed, approved);
+  }
+  if (parsed.toolId === KNOWLEDGE_TOOL) {
+    let userAgent = "";
+    try { userAgent = host.userAgent?.() ?? ""; } catch { /* report none rather than leave the call unanswered */ }
+    return knowledgeResult(parsed, userAgent);
+  }
+  return notFoundResult(parsed);
+}
+
+/** Tagged, not subclassed: worker bundles are built for a target without `class`. */
+export interface ClientToolError extends Error { kind: "client-tools" }
+
+function clientToolError(message: string): ClientToolError {
+  const e = new Error(message) as ClientToolError;
+  e.name = "ClientToolError";
+  e.kind = "client-tools";
+  return e;
+}
+
+export type ClientToolOutcome =
+  /** The response asked for nothing. */
+  | "none"
+  /** Every call was answered, and the last response asked for nothing more. */
+  | "answered"
+  /** The turn moved on while a call was being answered, so its result was never
+   *  sent. An approval given for a turn the owner has since left must not reach
+   *  the agent, which would act on it in a conversation nobody is watching. */
+  | "abandoned";
+
+export interface ClientToolExchange {
+  host?: AriaClientTools;
+  /** The calls a response is waiting on — `functionCallsOf` from the chat client. */
+  callsOf: (res: SendMessageResponse) => FunctionCall[];
+  /** Send one round of results; resolves with the service's next response. */
+  send: (results: FunctionCallResult[]) => Promise<SendMessageResponse>;
+  /** Is the turn these calls belong to still the current one? Asked after each
+   *  answer and before its result is sent. */
+  stillCurrent: () => boolean;
+  maxRounds?: number;
+  /** Handed the response that ended the exchange (the one asking for nothing
+   *  more). Its assistant row is the reply the owner is now owed. */
+  onFinal?: (res: SendMessageResponse) => void;
+  /** Run after a call is answered and before its result is sent — the last
+   *  moment at which everything in the transcript provably predates the result.
+   *  Must not reject. The turn is asked about again once it resolves, so a turn
+   *  that moved on while it ran is abandoned rather than answered. */
+  beforeSend?: () => Promise<void>;
+}
+
+/** Drive the whole exchange that `first` opens, one call at a time.
+ *
+ *  Rejects — failing the turn — on the two responses the other clients also
+ *  refuse: more than one call at once (the contract is one, and there is no
+ *  telling in which order an agent meant several to be asked), and a loop that
+ *  exceeds `maxRounds`. A failed send rejects too. */
+export async function runClientToolExchange(first: SendMessageResponse, x: ClientToolExchange): Promise<ClientToolOutcome> {
+  const max = x.maxRounds ?? CLIENT_TOOL_MAX_ROUNDS;
+  let current = first;
+  let rounds = 0;
+  for (;;) {
+    const calls = x.callsOf(current);
+    if (!calls.length) {
+      if (rounds) x.onFinal?.(current);
+      return rounds ? "answered" : "none";
+    }
+    // Asked BEFORE presenting anything, as well as after: between two rounds the
+    // modal is down and Stop is reachable, and a second question must not be put
+    // to the owner for a turn they have already stopped or left.
+    if (!x.stillCurrent()) return "abandoned";
+    if (calls.length > 1) throw clientToolError(`the assistant asked for ${calls.length} client tools at once`);
+    if (rounds >= max) throw clientToolError(`the assistant asked for more than ${max} client tools in one turn`);
+    const result = await answerClientTool(calls[0], x.host);
+    if (!x.stillCurrent()) return "abandoned";
+    if (x.beforeSend) {
+      await x.beforeSend();
+      if (!x.stillCurrent()) return "abandoned";
+    }
+    current = await x.send([result]);
+    rounds += 1;
+  }
+}

package/templates/gym-fitness-owner/tier5-src/himi-owner-lite-aria/index.ts

@@ -20,10 +20,14 @@
 //     targets are baked into the descriptor from the app contract, so a vertical
 //     this site has not installed can never be navigated to.
 //  4. Copy as configuration: every user-facing string goes through copyParam.
+//  5. Consent. When the agent asks before acting on the owner's account, the
+//     question is put to the owner in a real modal (`@himalaya/ui` alert) and
+//     their tap is the answer — see `confirmWithOwner`.
 
 import { defineService } from "@himalaya/state";
 import { open } from "@himalaya/open-url";
 import { writeText } from "@himalaya/clipboard";
+import { alert } from "@himalaya/ui";
 import {
   activeSiteId,
   createAriaChat,
@@ -132,6 +136,40 @@ export function screenForUrl(url: string, allowed: Set<string>): string {
   return best;
 }
 
+/** Put the agent's consent question to the owner, and return their answer.
+ *
+ *  A real MODAL, not a card in the chat: it has to cover the screen, because a
+ *  card leaves the composer, Stop and ➕ live beside a question the agent is
+ *  blocked on, and an answer tapped on a card that has scrolled away is how an
+ *  owner approves something they never read. `@himalaya/ui` presents the same
+ *  token-themed alert the platform uses everywhere, on iOS, Android and web.
+ *
+ *  The body is the agent's words (already plain text, and capped, by the core).
+ *  The title and both buttons are OURS: the agent may suggest button labels and
+ *  they are ignored, because a model that cannot tap Confirm can still try to
+ *  get it labelled "Cancel".
+ *
+ *  `confirmed` is only true for a tap on Confirm. A dismissal answers false — a
+ *  refusal. A host with no presenter REJECTS (`no_ui_host`), which the core
+ *  reports to the agent as "could not ask" — never as a yes. */
+async function confirmWithOwner(ask: { message: string }): Promise<boolean> {
+  const { confirmed } = await alert({
+    title: copyParam("ownerAria.consent.title", "Confirmation required"),
+    message: ask.message || copyParam("ownerAria.consent.body", "Approve to continue"),
+    confirmLabel: copyParam("ownerAria.consent.approve", "Confirm"),
+    cancelLabel: copyParam("ownerAria.consent.deny", "Deny"),
+  });
+  return confirmed === true;
+}
+
+/** What `getClientSideKnowledge` reports. The browser's own string where there
+ *  is one (the web host); the native worker runtimes have no `navigator`, and
+ *  the app's name is then the honest answer rather than an invented UA. */
+function userAgent(): string {
+  const nav = (globalThis as { navigator?: { userAgent?: unknown } }).navigator;
+  return typeof nav?.userAgent === "string" && nav.userAgent ? nav.userAgent : "himi-owner-lite";
+}
+
 const core = createAriaChat({
   // Mount the generic card for an unrecognised widget kind. This screen is
   // listed in `workerSubtreeScreens`; a screen that is not would have the node
@@ -161,7 +199,9 @@ const core = createAriaChat({
     // English. Says no "sign in": the owner already is, and the missing piece is
     // the app's binding, so there is no action for them to take.
     unavailable: () => copyParam("ownerAria.unavailable", "Aria can't reach your Wix account from here."),
+    toolFailed: () => copyParam("ownerAria.toolFailed", "Aria couldn't finish that. Try again."),
   },
+  clientTools: { confirm: confirmWithOwner, userAgent },
   historyKey: "ol.aria.history.v1",
   // No local title cache in THIS app. __HIMI_APP_NAME__ is multi-account and
   // multi-site: `himalaya.storage` is app-wide, survives the account-scoped

package/templates/himi-chat/dev/index.ts

@@ -1263,7 +1263,7 @@ const SCREENS = runtimeSetting({
                 "package": "himalaya",
                 "type": "Button",
                 "props": {
-                  "title": "",
+                  "title": "Send",
                   "iconOnly": true,
                   "leadingIcon": "arrow_up",
                   "style": "primary",
@@ -1285,7 +1285,7 @@ const SCREENS = runtimeSetting({
                 "package": "himalaya",
                 "type": "Button",
                 "props": {
-                  "title": "",
+                  "title": "Stop",
                   "iconOnly": true,
                   "leadingIcon": "stop",
                   "style": "primary",