@agent-cards/commerce-sdk 0.16.0 → 0.17.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')
@@ -110,8 +110,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 +370,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) {
@@ -550,6 +551,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 +587,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 +615,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 +752,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 +896,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 +972,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 +1016,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 +1053,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 +1674,31 @@ 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 planned = plan && 'body' in plan ? plan.body : 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 +1713,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 +1866,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 +1904,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 +1936,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.
             }
@@ -1837,6 +1956,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 +1975,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 +1999,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 +2022,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 +2086,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 +2119,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 +2301,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 +2353,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 +2380,59 @@ 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);
+        }
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
@@ -2262,6 +2487,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,13 +2511,26 @@ export function buyTool(options) {
             messageStream: {
                 value: () => {
                     writesThroughTurn = true;
-                    return feedStream(text, releaseForReply);
+                    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: (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);

package/dist/client.d.ts

@@ -127,6 +127,12 @@ export interface BuyStreamHandlers {
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
     /** Each message Agentcard writes, the moment it is written. */
     onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /**
+     * The line that says what Agentcard is looking for, such as `one sec, checking target for la croix`, written while the
+     * search runs on an ask for something new. It comes before the turn's cards and messages, or not at all, and the
+     * answer's `messages` never hold it.
+     */
+    onAck?: (update: BuySegmentUpdate) => void | Promise<void>;
     /** The carts, each time the turn builds or changes one. */
     onCart?: (update: BuyCartUpdate) => void | Promise<void>;
     /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
@@ -234,6 +240,8 @@ export interface BuyRequest {
     delivery_address?: BuyDeliveryAddress;
     external_user_id?: string;
     user_id?: string;
+    /** `false` asks for no line that says what Agentcard is looking for (`onAck`): the shopper already read one. */
+    ack?: false;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
 export interface BuyStore {

package/dist/client.js

@@ -11,7 +11,7 @@
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta', 'onAvailability'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -535,6 +535,9 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
                 deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
             }
+            else if (event === 'ack' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onAck) {
+                deliver(() => stream.onAck({ conversationId: named, text: data.text }));
+            }
             else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
                 const items = data.items.filter(isRecord).flatMap((i) => {
                     const id = str(i.id);

package/dist/definition.js

@@ -13,6 +13,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
     'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
     "When `shopper_already_told_looking` is true, the shopper already knows you are working on their request, from a reply or a 👀 on their message, so never acknowledge it again: open with the answer or the question.",
+    'When the shopper asks you to find, buy, book or order something new, such as a product, a gift idea, a meal, a table, a flight or a store page they pasted a link to, first write one short line that says what you are about to look for, then call this tool in the same reply: only what they asked for, and the store or place they named, in their own words, such as "on it, looking for la croix at target", "one sec, checking nopa for a table for 2 at 7pm" or, for a pasted link, "one sec, checking that link", never a price, a total, stock, a result, a question or that anything was found, added or ordered. A store named by its site, such as "the polishing cloth from myrqvist.com", is a store, not a link. For a yes, a pick, a size, an address, a code, a change to a cart or a question about an order, write no line first, and after this tool answers, never say again that you are looking.',
     'When `shopper_already_read_reply` is true, the shopper already read `reply` as Agentcard wrote it, so never say it again in any words: answer with only what `reply` leaves out, in one short line, or with nothing.',
     'Show the shopper the cart before you confirm it.',
     'When `cart_building` is set, the store is still building that cart: tell the shopper in one short line that its total is on its way, never ask them to confirm it, and confirm it only after they say yes to the total in the message Agentcard sends next.',

package/dist/direct.d.ts

@@ -21,11 +21,21 @@ export interface DirectContext {
     nextAction?: BuyNextAction | null;
     /** Agentcard's last reply, the question a short answer answers. */
     asked?: string | null;
-    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. */
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. A place (`the second one`) reads these. */
     products?: ReadonlyArray<{
         productId: string | null;
         name: string;
     }>;
+    /**
+     * Every product card the shopper can tap by its name, each once: the answer's and the ones its searches sent as they answered,
+     * which an answer about one item can leave out (a menu turn that answered with the Burrito beside eight menu cards). A pick by
+     * name (a card's tap, a product's whole name, a word only one name holds) reads these; a place never does, so `the last one` is
+     * the last of `products`. Left out, `products` stands for both.
+     */
+    tappable?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
     /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
     stores?: ReadonlyArray<{
         storeId: string;