@agent-cards/commerce-sdk 0.16.0 → 0.18.0

package/dist/buy-tool.js

@@ -36,10 +36,10 @@ import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolIn
 import { directCall, isProductAsk } from './direct.js';
 import { forModel, forModelError, pickId, productPrice, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, replyAsWritten, textingStyle } from './texting.js';
-import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
+import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
-import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
+import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
     if (merchant === 'reservations')
@@ -75,6 +75,10 @@ export function turnMessages(history, told, shopperText) {
     out.push({ role: 'user', content: shopperText });
     return out;
 }
+/** The note a message carries to the model when Agentcard already answered it and left the words to the model (`handled()`). */
+export function handedNote(answer) {
+    return `[Agentcard already answered this message with the buy tool. Its answer, for you to tell the shopper in your words, without calling the tool again for it: ${answer}]`;
+}
 /** What the model reads of a message Agentcard posted into the chat: its text with every link taken out, as `forModel` takes them out. */
 const modelText = (message) => stripLinks(String(message.text ?? ''));
 /** How often the history held a message's text when the message first went in to the model. */
@@ -110,8 +114,8 @@ const RESUME_SKEW_MS = 2 * 60_000;
 const STOPPED_ORDER = new Set(['failed', 'cancelled']);
 /** The refusals a confirm gets once the order took the cart, or while the placement still runs. */
 const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 'turn_in_progress']);
-/** How long Agentcard has to answer before the instant reply goes out. */
-const ACK_DELAY_MS = 1_500;
+/** How long a turn shows the shopper nothing before the line that says it is on it goes out. */
+const ACK_DELAY_MS = 1_000;
 /** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
 const SAME_TURN_MS = 15_000;
 /** A product name shorter than this, such as `AA`, is too short to tell a pick from a search. */
@@ -370,7 +374,8 @@ function onlyNextStepLinks(result, next) {
  */
 function withMessages(result, turn) {
     const sent = turn && result.reply === turn.reply && turn.messages.length > 0 ? turn.messages : [result.reply];
-    return { ...result, messages: sent.flatMap(toMessages) };
+    // One joiner across every message, so a message that is only a lead-in goes with the next one rather than out of the list.
+    return { ...result, messages: joinLeadIns(sent.flatMap(paragraphsOf)) };
 }
 /** True when the app showed every message of an answer that has one, each as written and in order. */
 function readEvery(told, messages) {
@@ -532,6 +537,13 @@ function needsCard(link, body) {
         envelope: body,
     };
 }
+/**
+ * One shopper message's turn: the calls the model makes for it share its number, its instant reply and
+ * the callbacks its links and answers go to. `links` and `results` collect for a turn `buy.turn` opened,
+ * and are null for a call made straight on the tool.
+ */
+/** What a call throws when Agentcard handed the message back to the app's model (`BuyToolTurn.handled`). */
+const HANDED_BACK = Symbol('handed back');
 /** The way a turn hands over a link, or undefined when it has nowhere to send one. */
 function senderOf(t) {
     if (!t.sendLink && !t.links)
@@ -550,6 +562,8 @@ function senderOf(t) {
  */
 function itemFeed(pauseOf, typing) {
     const items = [];
+    // How many items joined the feed, sent or still going out: one means the shopper has something to read.
+    let pushed = 0;
     // The item going out now, or null when none is: an item pushed while none is goes out at once.
     let tail = null;
     let lastAt = null;
@@ -584,6 +598,7 @@ function itemFeed(pauseOf, typing) {
      * unlisted, with no pause, as for the rest of a reply whose earlier message failed.
      */
     const push = (item, send, skip = () => false) => {
+        pushed += 1;
         // Each message's pause is chosen once, when it joins the feed, so a pace that varies never makes it wait twice.
         const pause = item.kind === 'text' && pauseOf ? pauseOf(item.text) : 0;
         const waitFor = () => (pause > 0 && lastAt !== null ? lastAt + pause - Date.now() : 0);
@@ -611,7 +626,7 @@ function itemFeed(pauseOf, typing) {
         tail = settled;
         return run;
     };
-    return { items, push };
+    return { items, push, pushed: () => pushed };
 }
 /**
  * One reply's messages in a turn's feed: each one takes its place in the feed the moment it is cut,
@@ -748,6 +763,8 @@ export function buyTool(options) {
         throw new TypeError('Pass earlyCards as true or false.');
     // A search's cards go out the moment it answers, unless the app waits for the answer that names them.
     const earlyCards = o.earlyCards !== false;
+    // Every call streams unless the app waits for whole answers (`stream: false`).
+    const streamCalls = o.stream !== false;
     if (o.onResult !== undefined && typeof o.onResult !== 'function') {
         throw new TypeError('Pass onResult as a function that takes each answer.');
     }
@@ -890,6 +907,8 @@ export function buyTool(options) {
     };
     /** What the last answer showed, products and stores with the ids a pick sends, and the turn the shopper opened last. */
     let lastAnswerProducts = [];
+    /** Every product card of the last answer's call the shopper can tap by name, each once (the answer's and the streamed). */
+    let lastTappable = [];
     let lastAnswerStores = [];
     let previousTurn = null;
     /** The names of the stores the last answer that listed stores showed: a message that names one, as a tap on its card does, picks it. */
@@ -964,8 +983,42 @@ export function buyTool(options) {
     const holdAck = (ask, t, step = null) => {
         const onWorking = t.onWorking;
         const reacting = t.onReaction;
-        if ((!onWorking && !reacting) || t.acked)
+        // A turn the app ended (`turn.end()`) holds no acknowledgement for a call it still runs.
+        if ((!onWorking && !reacting) || t.acked || t.ended)
             return null;
+        const model = t.modelTurn;
+        if (model && onWorking && model.writesThrough()) {
+            // The app's model called the tool. When it wrote its own line first, that line is the turn's acknowledgement; when
+            // its first output is this call, the shopper hears the wait line, no sooner than ackDelayMs after the turn opened.
+            model.callStarted = true;
+            if (model.spoke || model.shown())
+                return null;
+            t.acked = true;
+            const line = slowStepLine(step === 'confirm' ? 'confirm' : step ?? t.picked ?? 'wait');
+            let waiting = true;
+            const waitTimer = setTimeout(() => {
+                waiting = false;
+                // The model may have written its own line while this call ran: that line is the turn's acknowledgement, so the
+                // wait line is dropped and the turn's reply is free for a later call.
+                if (model.spoke || model.shown() || t.ended) {
+                    t.acked = false;
+                    return;
+                }
+                t.waitLineOut = true;
+                t.ackOut = Promise.resolve()
+                    .then(() => onWorking(line))
+                    .then(() => { t.ackDelivered = true; }, () => { });
+            }, Math.max(0, model.openedAt + ackDelayMs - Date.now()));
+            return {
+                cancel: () => {
+                    if (!waiting)
+                        return;
+                    waiting = false;
+                    clearTimeout(waitTimer);
+                    t.acked = false;
+                },
+            };
+        }
         // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
         const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
         // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
@@ -974,10 +1027,19 @@ export function buyTool(options) {
         // A slow call of any message may get the 👀, which reads nothing back; only a text reply needs one of these.
         if (!reacting && !slow && !neutral && !isNewRequest(ask))
             return null;
+        // A streamed search's line is Agentcard's (onAck), written from the conversation while it searches: the tool adds no
+        // template of its own, unless the app writes the words.
+        if (!reacting && !slow && !neutral && streamCalls && !writeAck)
+            return null;
         t.acked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
+            // The app ended the turn while this call ran, as after its model failed: no 👀 and no line follow its error.
+            if (t.ended) {
+                t.acked = false;
+                return;
+            }
             // With reactions, a slow call puts the message's one 👀 on it, and never adds a line of text.
             if (reacting) {
                 react(t, reacting);
@@ -1002,7 +1064,7 @@ export function buyTool(options) {
                 lastTemplate = nextTemplate(lastTemplate);
                 // A neutral turn's message, such as `yes` or `ok lets checkout`, is no search: its reply says the
                 // tool is working, and never that it is looking for anything.
-                text = neutral ? waitAt(lastTemplate) : ackAt(lastTemplate, ask);
+                text = neutral ? slowStepLine('wait') : ackAt(lastTemplate, ask);
             }
             if (typeof text !== 'string' || text.trim() === '') {
                 t.acked = false;
@@ -1623,20 +1685,33 @@ export function buyTool(options) {
         // A turn the tool took on its own sends no ask: it reads where the purchase stands, and only the
         // shopper's own yes to this exact cart goes in, for that cart's hash.
         const plan = t.event ? await stepPlan(t.event) : null;
-        const sent = plan && 'body' in plan ? plan.body : body;
-        const confirmSent = plan ? 'body' in plan && sent.confirm !== undefined : confirm;
+        const handBack = t.handBack ?? null;
+        t.handBack = null;
+        const planned = plan && 'body' in plan ? plan.body : handBack ? { ...body, hand_back: true, last_answer: handBack } : body;
+        const confirmSent = plan ? 'body' in plan && planned.confirm !== undefined : confirm;
+        // Agentcard writes the line that says what it is looking for (onAck) only where the shopper can read it before the
+        // cards and has read nothing yet: a streamed ask, with somewhere to show it, that no reaction, reply or model's words
+        // acknowledged already, in an app that asked for no acknowledgement of its own (`ack: 'none'` or `ack: false` gets
+        // none, there as here) and acknowledges in text: an app that reacts (`ack: 'reaction'`, or an `onReaction` the turn
+        // routes to) reads no line of text, even through `onText`. Every other ask says so, and Agentcard spends no model call on it.
+        const agentcardAcks = streamCalls && ackMode !== 'none' && ackMode !== 'reaction' && !t.onReaction && !t.event && !confirmSent && !pick && !t.acked && (!!t.onWorking || !!t.onText) && (t.agentcardAcks?.(ask) ?? false);
+        /** What goes to Agentcard: the planned request, with `ack: false` when the shopper reads no line of Agentcard's. */
+        let sent = planned;
         const callTurn = t.number;
         const send = senderOf(t);
         const progressOf = t.onProgress;
         // Every call streams unless the app waits for whole answers, so each part reaches the app as Agentcard produces it. A
         // confirm streams as a search does, and only a search's products go out early. A call with no callback to hear any part
         // has no handler, and the client asks for the whole answer.
-        const streams = o.stream !== false;
+        const streams = streamCalls;
         const early = earlyCards && !!send && !confirmSent;
         running += 1;
+        t.called = true;
         // A confirm or a pick of what the shopper saw never hears "looking for": once the call is slow, it hears a
         // fixed line that names nothing they said (slowStepLine), so a 20-second checkout or menu read is never silent.
         const ack = t.event ? null : holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
+        if (ack)
+            (t.holds ??= new Set()).add(ack.cancel);
         /** Says `unknown` of every card the call left `checking`; it runs once the answer's cards went out, or when the call fails. */
         let settleLeft = null;
         try {
@@ -1651,16 +1726,51 @@ export function buyTool(options) {
             const waiting = [];
             /** True when the last message the shopper read ended in a colon or a question mark, so choices that open the next one are its list. */
             let leadIn = false;
-            /** Shows one of Agentcard's messages through onText, its lists as bullets (messageForShopper); `told` keeps it as Agentcard wrote it. */
+            /** A message that leads in with a colon waits for the one after it (leadInJoiner), and `heldTexts` keeps it as Agentcard wrote it. */
+            let leads = leadInJoiner();
+            let heldTexts = [];
+            /** Shows a message through onText, its lists as bullets (messageForShopper); `told` keeps each of Agentcard's messages in it as written. */
+            const showMessage = async (message, texts, conversationId) => {
+                await t.onText(messageForShopper(message, leadIn, t.texting), { conversationId });
+                leadIn = leadsIntoList(message);
+                told.push(...texts);
+            };
+            /**
+             * Shows one of Agentcard's messages through onText. One that ends on a colon, such as `two options came in under $20:`,
+             * goes out with the message after it, so the shopper never reads a bubble ending on a colon.
+             */
             const showText = async (text, conversationId) => {
-                await t.onText(messageForShopper(text, leadIn, t.texting), { conversationId });
-                leadIn = leadsIntoList(text);
-                told.push(text);
+                const message = leads.add(text);
+                heldTexts.push({ text, conversationId });
+                if (message === null)
+                    return;
+                const texts = heldTexts.map((held) => held.text);
+                heldTexts = [];
+                await showMessage(message, texts, conversationId);
+            };
+            /**
+             * A lead-in no message followed, once the answer is in: its list went (the cards show it), so it goes out less its colon
+             * sentence, and not at all when that was all of it. It counts as read when anything was, so the model never words again
+             * what the shopper read.
+             */
+            const showLeftLead = async () => {
+                if (heldTexts.length === 0)
+                    return;
+                const rest = leads.end();
+                const texts = heldTexts.map((held) => held.text);
+                const conversationId = heldTexts[0].conversationId;
+                heldTexts = [];
+                if (rest)
+                    await showMessage(rest, texts, conversationId);
+                else if (told.length > 0)
+                    told.push(...texts);
             };
             /** The products past the cards of the catalog this call heard last, for the count that follows it. */
             let moreFound = null;
             /** Whether this call's cards went out, and a count that came before them. */
             let cardsOut = false;
+            /** The product cards this call's searches sent out as they answered, which the shopper can tap whatever the answer lists. */
+            const streamedCards = [];
             let heldCount = null;
             /** The card each catalog id of this call went out as (its `productId`), and the cards still `checking`, by conversation. */
             const cardOfId = new Map();
@@ -1769,6 +1879,7 @@ export function buyTool(options) {
                                 await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
                                 // A place shown `checking`, on a card or behind "show more", waits for the live search's word on it.
                                 noteCards([...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })], update.conversationId);
+                                streamedCards.push(...productsOfCatalog(update.catalog));
                                 keepMore();
                                 cardsOut = true;
                                 // A count held for these cards goes out now, unless the catalog carries its own, which follows it.
@@ -1806,6 +1917,24 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(agentcardAcks
+                        ? {
+                            // Agentcard's line for the search, such as `one sec, checking target for la croix`: it goes out as the turn's
+                            // instant reply, through onWorking, else as Agentcard's message, and only while the shopper has read nothing
+                            // else of the turn. The model then reads `shopper_already_told_looking`.
+                            onAck: async ({ text, conversationId }) => {
+                                if (t.acked || cardsOut || told.length > 0 || waiting.length > 0)
+                                    return;
+                                ack?.cancel();
+                                t.acked = true;
+                                const line = text.trim();
+                                t.ackOut = Promise.resolve()
+                                    .then(() => (t.onWorking ? t.onWorking(line) : t.onText?.(line, { conversationId })))
+                                    .then(() => { t.ackDelivered = true; }, () => { });
+                                await t.ackOut;
+                            },
+                        }
+                        : {}),
                     ...(t.onCart
                         ? {
                             onCart: async ({ cart, carts, conversationId }) => {
@@ -1820,6 +1949,9 @@ export function buyTool(options) {
                         : {}),
                 }
                 : undefined;
+            // A streamed ask for something new that the tool shows no line of Agentcard's for says so. A pick never gets one.
+            const streamed = !!handlers && Object.values(handlers).some((handler) => typeof handler === 'function');
+            sent = planned.ask !== undefined && !planned.pick && streamed && !agentcardAcks ? { ...planned, ack: false } : planned;
             if (plan && 'local' in plan) {
                 // Nothing went to Agentcard: the answer is where the purchase stands.
             }
@@ -1830,6 +1962,9 @@ export function buyTool(options) {
                 catch (error) {
                     refusal = error;
                 }
+                // Agentcard read the message as your model's: nothing ran, so the call ends here and the turn's model answers it.
+                if (turn?.handed_back)
+                    throw HANDED_BACK;
             }
             // The store was still building the last request's cart: once it is in, the request that was refused goes as it was
             // sent, a step's own request too (a saved ask is no longer saved once its step sent it).
@@ -1837,6 +1972,8 @@ export function buyTool(options) {
                 // Only the answer of the request sent again counts toward what the shopper read.
                 told.length = 0;
                 waiting.length = 0;
+                leads = leadInJoiner();
+                heldTexts = [];
                 try {
                     turn = await client.buy(sent, handlers);
                     refusal = undefined;
@@ -1854,7 +1991,8 @@ export function buyTool(options) {
             let replaced = false;
             if (waiting.length > 0 && t.onText) {
                 const rewritten = !!turn && settled.reply !== turn.reply;
-                const kept = new Set((rewritten ? toMessages(settled.reply) : []).map((message) => message.trim()));
+                // Paragraph for paragraph, as `told` keeps Agentcard's messages, before any lead-in joins the one after it.
+                const kept = new Set((rewritten ? paragraphsOf(settled.reply) : []).map((message) => message.trim()));
                 for (const message of waiting.splice(0)) {
                     if (rewritten && waitsForAnswer(message.text) && !kept.has(message.text.trim())) {
                         replaced = true;
@@ -1877,6 +2015,14 @@ export function buyTool(options) {
                     }
                 }
             }
+            if (t.onText) {
+                try {
+                    await showLeftLead();
+                }
+                catch {
+                    // A message the app failed to show was never read, so the model words the answer.
+                }
+            }
             // Every message of Agentcard's own answer reached the shopper through onText, so the model adds nothing to it. An answer
             // whose card ask gave way to the named step was read the same way once every message of it, that ask last, went out.
             // A reply the shopper read that asks them to choose, with the values named inside a sentence or not at all, is followed
@@ -1892,7 +2038,7 @@ export function buyTool(options) {
                     choiceShown = false;
                 }
             }
-            const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, toMessages(settled.reply)));
+            const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, paragraphsOf(settled.reply)));
             const answer = withMessages(settled, turn);
             const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
             // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
@@ -1956,7 +2102,23 @@ export function buyTool(options) {
             const storesShown = shownStores(result.stores);
             if (storesShown.length > 0)
                 shownStoreNames = storesShown.map((store) => store.name);
+            // The cards the shopper can tap by name are the answer's and the ones this call's searches already sent: a restaurant turn that
+            // read the Burrito's options answered with the Burrito alone, beside the eight menu cards it sent first, and a tap on the
+            // Burrito Bowl then found no card of its name. A place ("the last one") reads the answer's own list, in its order, and never
+            // this one, so it picks the product shown in that place (Greptile on #11163).
+            // Each card once, by its id: a call that sends one search's products again (a refreshed catalog) would otherwise hold the
+            // same card twice, and a tap on it would read as two cards named alike (Greptile on #11163).
+            const tappable = [];
+            const held = new Set();
+            for (const product of [...shown, ...shownProducts(streamedCards)]) {
+                const id = pickId(product) ?? `name:${product.name}`;
+                if (held.has(id))
+                    continue;
+                held.add(id);
+                tappable.push(product);
+            }
             lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
+            lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
             lastAnswerStores = storesShown.map((store) => ({ storeId: store.id, name: store.name }));
             t.results?.push(result);
             if (t.onResult) {
@@ -1973,6 +2135,9 @@ export function buyTool(options) {
             // A call that fails, Agentcard's error or a thrown handler, still settles the cards it left `checking`.
             await settleLeft?.().catch(() => { });
             ack?.cancel();
+            if (ack)
+                t.holds?.delete(ack.cancel);
+            t.dropWaitLine?.();
             running -= 1;
             lastEndedAt = Date.now();
         }
@@ -2152,7 +2317,29 @@ export function buyTool(options) {
             return Promise.resolve();
         };
         /** A message the app's model wrote: it goes to onItem, else onMessage, after every item before it, and the turn lists it. */
-        const text = (message, skip) => feed.push({ kind: 'text', text: message }, () => (onItem ? onItem({ kind: 'text', text: message }) : onMessage?.(message)), skip);
+        let modelWrote = false;
+        /** Whether the model's first words came before any call of the turn: set by its first delta or `say`, since a paragraph is cut later. */
+        let wordsBeforeCall = null;
+        const firstWords = (words) => {
+            if (wordsBeforeCall === null && /\S/.test(String(words ?? '')))
+                wordsBeforeCall = !state.called;
+        };
+        const text = (message, skip) => {
+            const first = !modelWrote;
+            modelWrote = true;
+            const show = (left) => feed.push({ kind: 'text', text: message }, () => (onItem ? onItem({ kind: 'text', text: message }) : onMessage?.(message)), left);
+            // The wait line already told the shopper the turn is on it: the model's own acknowledgement, its first message
+            // written before any call, such as `on it, looking for a dryer under $20`, would be a second line, so it stays in
+            // the model's own history and never reaches the shopper. A first message that asks, answers or says what a search
+            // came to still goes out, and so does every message after it. (2026-10-27: "dryer under 20" read `one moment`,
+            // then `on it, looking for a dryer under $20`.)
+            // A wait line the app failed to send reached nobody (`ackDelivered`), so the model's own line goes out in its
+            // place, in the feed's order: a failed send costs that line alone, never both.
+            if (first && state.waitLineOut && (wordsBeforeCall ?? !state.called) && readsAsAckLine(message)) {
+                return show(() => state.ackDelivered || (skip?.() ?? false));
+            }
+            return show(skip);
+        };
         let ack = null;
         const working = state.onWorking;
         const reacting = state.onReaction;
@@ -2182,7 +2369,9 @@ export function buyTool(options) {
                 // A search gets its 👀 the moment the turn opens, and no text: the reaction reads nothing back.
                 react(state, reacting);
             }
-            else if (text !== null && working) {
+            else if (text !== null && working && (writeAck || !streamCalls)) {
+                // A streamed search's line is Agentcard's to write (onAck), from the conversation, while it searches; the
+                // tool's template goes out at once only for an answer the app waits for whole, or in the app's own words.
                 ack = text;
                 state.acked = true;
                 let sent;
@@ -2207,7 +2396,71 @@ export function buyTool(options) {
             ? null
             : event
                 ? { input: { ask: NEXT_STEP_ASK, confirm: false, new_order: false, product_id: null, store_id: null }, reason: 'next_step' }
-                : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, stores: lastAnswerStores });
+                : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, stores: lastAnswerStores });
+        // Agentcard writes the line for a search the turn sends straight. A turn the app's model runs gets the model's own line,
+        // or the wait line below.
+        state.agentcardAcks = (ask) => direct !== null && direct.reason === 'product_ask' && ask.trim() === direct.input.ask.trim();
+        /** Says the turn is on it, once, in fixed words that name nothing the shopper said, unless something went out first. */
+        const sayWaiting = (line) => {
+            if (state.acked || state.ended || feed.pushed() > 0 || !writesThroughTurn)
+                return;
+            state.acked = true;
+            state.waitLineOut = true;
+            state.ackOut = Promise.resolve()
+                .then(() => working(line))
+                .then(() => { state.ackDelivered = true; }, () => { });
+        };
+        // Only where the tool sees what the shopper read: the app writes the model's words through the turn.
+        if (!event && working && !reacting && direct !== null && direct.reason !== 'product_ask') {
+            // A pick, a confirm or an answer the turn sends straight that has shown nothing after ackDelayMs says it is on it. A
+            // product ask hears Agentcard's line (onAck).
+            const waitTimer = setTimeout(() => sayWaiting(slowStepLine(direct.reason === 'confirm' ? 'confirm' : state.picked ?? 'wait')), ackDelayMs);
+            waitTimer.unref?.();
+            // A call that ended, by its answer or by its error, leaves the turn to its reply: no wait line follows a failed pick.
+            state.dropWaitLine = () => clearTimeout(waitTimer);
+        }
+        else if (!event && working && !reacting && direct !== null) {
+            // A search the turn sends straight hears Agentcard's line (onAck). When that line never comes, as when Agentcard's
+            // model writes none or its line is dropped, and the shopper has seen nothing, no line and no card, by twice
+            // ackDelayMs, the wait line goes out then, the same rule as a model that has written nothing and called nothing.
+            // Once it went out, a line of Agentcard's that comes later is dropped (onAck reads `acked`), so the shopper reads one
+            // line. A call that already answered leaves the turn to its reply. (2026-10-27: "i want one called ardor" showed
+            // nothing for 9.1 s.)
+            const waitTimer = setTimeout(() => {
+                if (results.length === 0)
+                    sayWaiting(slowStepLine('wait'));
+            }, 2 * ackDelayMs);
+            waitTimer.unref?.();
+            // A call that ended, by its answer or by its error, leaves the turn to its reply: no wait line follows a failed search.
+            state.dropWaitLine = () => clearTimeout(waitTimer);
+        }
+        else if (!event && working && !reacting && direct === null) {
+            // The app's model runs this turn, and its first output decides: its own line first means no wait line; a call first
+            // gets the wait line from that call (holdAck); and a model that has written nothing and called nothing after twice
+            // ackDelayMs gets it then.
+            const model = { openedAt: Date.now(), spoke: false, callStarted: false, writesThrough: () => writesThroughTurn, shown: () => feed.pushed() > 0 };
+            state.modelTurn = model;
+            const waitTimer = setTimeout(() => {
+                if (!model.spoke && !model.callStarted)
+                    sayWaiting(slowStepLine(state.picked ?? 'wait'));
+            }, 2 * ackDelayMs);
+            waitTimer.unref?.();
+            // `turn.end()`, as when the app's model failed before it wrote or called anything, stops it: no `one moment` follows
+            // the app's own error. A call that ends stops it too, since a call started means the timer would send nothing.
+            state.dropWaitLine = () => clearTimeout(waitTimer);
+        }
+        // What Agentcard last showed and asked when the turn opened, for `handled()`: its call changes them once it answers.
+        const lastAnswer = {
+            answered,
+            next_action: lastNextAction ?? null,
+            asked: lastReply ?? null,
+            products: lastAnswerProducts.map((product) => ({ product_id: product.productId, name: product.name })),
+            stores: lastAnswerStores.map((store) => ({ store_id: store.storeId, name: store.name })),
+        };
+        const openedWhileRunning = running > 0;
+        const openedNextAction = lastNextAction;
+        const openedProducts = lastAnswerProducts;
+        const openedStores = lastAnswerStores;
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
@@ -2246,9 +2499,70 @@ export function buyTool(options) {
             if (saved.length > 0)
                 client.forgetMessages(externalUserId, saved);
             handed = fresh;
-            return turnMessages(history, fresh.map(modelText), shopperWords);
+            // A message Agentcard answered for the model to word goes in with that answer, so the model words it and calls nothing again.
+            return turnMessages(history, fresh.map(modelText), handedAnswer === null ? shopperWords : `${shopperWords}\n\n${handedNote(handedAnswer)}`);
+        };
+        /** Says a whole text as the turn's messages, after every item before it (`say()`). */
+        const sayWhole = (whole) => {
+            writesThroughTurn = true;
+            firstWords(whole);
+            if (state.modelTurn && /\S/.test(String(whole ?? '')))
+                state.modelTurn.spoke = true;
+            const reply = feedReply(text);
+            for (const message of toMessages(whole))
+                reply.add(message);
+            const released = releaseForReply();
+            released.catch(() => { });
+            return reply.settled().then(() => released);
+        };
+        /** Agentcard's answer, as the model reads it, when `handled()` left the words to the model. */
+        let handedAnswer = null;
+        let handledRun = null;
+        /**
+         * One call to Agentcard with the shopper's message (`BuyToolTurn.handled`). A pick by its id or a yes to the total the
+         * tool reads itself goes as that call; every other message goes as its words, with `hand_back`, and Agentcard decides.
+         */
+        const runHandled = async () => {
+            const words = String(shopperText ?? '');
+            if (event || openedWhileRunning || words.trim() === '')
+                return false;
+            const local = directCall(words, { answered, nextAction: openedNextAction, asked: lastAnswer.asked, products: openedProducts, stores: openedStores });
+            const exact = !!local && (local.input.confirm || local.input.product_id !== null || local.input.store_id !== null);
+            const input = exact ? local.input : { ask: words, confirm: false, new_order: false, product_id: null, store_id: null };
+            if (!exact) {
+                state.handBack = lastAnswer;
+                // Agentcard writes the line that says what it is looking for on a search this call starts, as on a search the turn
+                // sends straight (`direct`); a message it hands back gets none, since nothing runs.
+                state.agentcardAcks = (ask) => ask.trim() === words.trim();
+            }
+            let result;
+            try {
+                result = await answerIn(input, state);
+            }
+            catch (error) {
+                state.handBack = null;
+                if (error === HANDED_BACK)
+                    return false;
+                throw error;
+            }
+            if (result.shopper_already_read_reply === true)
+                return true;
+            const reply = replyAsWritten(result, { textingStyle: texting });
+            // The reply goes out where the app hears the turn's messages: onItem or onMessage, else onText. With none of them, the
+            // shopper would read nothing, so the app's model words the answer instead.
+            if (reply !== null && (onItem || onMessage)) {
+                await sayWhole(reply);
+                return true;
+            }
+            if (reply !== null && state.onText) {
+                await state.onText(reply, { conversationId: result.conversation_id });
+                return true;
+            }
+            handedAnswer = JSON.stringify(forModel(result));
+            return false;
         };
         return toolOf((raw) => answerIn(raw, state), {}, {
+            handled: { value: () => (handledRun ??= runHandled()), enumerable: false },
             agentcardMessages: { get: () => [...(handed ?? kept)], enumerable: false },
             event: { value: event, enumerable: false },
             release: {
@@ -2262,6 +2576,17 @@ export function buyTool(options) {
                 },
                 enumerable: false,
             },
+            end: {
+                value: () => {
+                    state.ended = true;
+                    state.dropWaitLine?.();
+                    // The acknowledgement a call still running holds, a 👀 or a line for a slow pick, confirm or answer, is cancelled too.
+                    for (const cancel of state.holds ?? [])
+                        cancel();
+                    state.holds?.clear();
+                },
+                enumerable: false,
+            },
             messages: { value: messagesFor, enumerable: false },
             ack: { value: ack, enumerable: false },
             reaction: { get: () => state.reaction, enumerable: false },
@@ -2275,22 +2600,21 @@ export function buyTool(options) {
             messageStream: {
                 value: () => {
                     writesThroughTurn = true;
-                    return feedStream(text, releaseForReply);
-                },
-                enumerable: false,
-            },
-            say: {
-                value: (whole) => {
-                    writesThroughTurn = true;
-                    const reply = feedReply(text);
-                    for (const message of toMessages(whole))
-                        reply.add(message);
-                    const released = releaseForReply();
-                    released.catch(() => { });
-                    return reply.settled().then(() => released);
+                    const stream = feedStream(text, releaseForReply);
+                    return {
+                        push: (delta) => {
+                            firstWords(delta);
+                            // The model's first words: its own line is the turn's acknowledgement, so no wait line follows.
+                            if (state.modelTurn && /\S/.test(String(delta ?? '')))
+                                state.modelTurn.spoke = true;
+                            stream.push(delta);
+                        },
+                        end: () => stream.end(),
+                    };
                 },
                 enumerable: false,
             },
+            say: { value: sayWhole, enumerable: false },
         });
     };
     return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});