@agent-cards/commerce-sdk 0.18.4 → 0.18.6

package/dist/buy-tool.js

@@ -1,44 +1,12 @@
-/**
- * The buy tool: one call that buys for one shopper, in one object that every
- * agent framework takes. `answer` sends the model's input to Agentcard and
- * returns the whole answer for your code, with the status, Agentcard's
- * reply, the cart and its hash, the products and the links. `forModel` turns
- * that answer into what the model may read, with every link taken out, and
- * `run`, `execute` and `handle` return that view as JSON text. A link
- * reaches the shopper through `sendLink`, and each call waits for it before
- * it returns: the Vault and approval links, then the store page of each
- * product the model reads.
- *
- * Agentcard keeps the conversation: every call continues the shopper's open
- * purchase (`resume: true`), and a confirm places the cart Agentcard last
- * showed (`confirm: true`). The tool keeps one thing between calls: the store
- * pages it sent last. Agentcard repeats the last search in each answer for a
- * while, so a list it shows again in the same conversation does not reach
- * the shopper twice. A tool built for each message buys the same way, and
- * sends such a list again.
- *
- * Two answers make the tool wait before it returns. A placement Agentcard is
- * still finishing gets one 12-second pause and one read of the conversation.
- * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
- * to a minute, until the turn ends.
- *
- * `turn` binds the tool to one shopper message: the calls the model makes
- * through it hand their links, answers and instant reply to that turn's own
- * callbacks and lists, so a shopper who sends a second message before the
- * first is answered never gets one message's cards beside the other's reply.
- * Every turn of one tool still shares the shopper's conversation state, such
- * as the store pages already sent. A turn with `onItem` hands the app its
- * messages and links as one sequence, in the order they happened, and spaces
- * the messages like someone texting.
- */
 import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 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 { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
-import { isStale } from './shopper-message.js';
+import { isStale, messageInChat } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
+import { checkStoreWait, storeWaitFields, withLateCards } from './store-wait.js';
 import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, 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) {
@@ -81,7 +49,7 @@ export function handedNote(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. */
+/** How often each chat's history held a message's text when the message first went in to its model, by `threadId` ('' for none). */
 const offeredAt = new WeakMap();
 /** How many times `needle` appears in `haystack`, none overlapping. */
 function occurrences(haystack, needle) {
@@ -151,6 +119,8 @@ const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shoppe
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
 const STORE_PICK_GONE = "The store the shopper picked is no longer among the stores Agentcard found, so no store was chosen. Call this tool again with the shopper's words and store_id null, and Agentcard searches again.";
+/** The most product cards a tool keeps from earlier answers for a tap on an older card. */
+const SHOWN_BEFORE_MAX = 200;
 const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
 /** One cart line as the order holds it: the product, its variant, its choices and its quantity. Prices are left out. */
 const lineKey = (line) => JSON.stringify([line.product_id ?? String(line.name ?? '').trim().toLowerCase(), line.variant ?? null, [...(line.options ?? [])].sort(), line.qty]);
@@ -352,6 +322,7 @@ function answerOf(turn) {
         hashes: hashesOf(turn.cart, turn.carts),
         cart_building: turn.cart_building,
         choice: turn.choice ?? null,
+        plan: turn.plan ?? null,
         envelope: turn.raw,
     };
 }
@@ -419,6 +390,13 @@ const CARD_ASK = /\b(?:add|save|link|enter|attach)\s+(?:a|your|the)\s+(?:(?:paym
  * which `askingForNamedStep` replaces when Agentcard names a step that comes first. Every message after it waits behind
  * it, so the shopper reads them in order; a message before it goes out at once.
  */
+/**
+ * Agentcard's messages of an answer, as written, that the shopper read in full through the early reply (onWrittenText)
+ * before the call ended, by the answer they belong to. `turn.replyAsWritten` hands them back for the turn's last answer and
+ * `turn.say` of them sends nothing, so the app shows no second reply and its model is not asked to word one
+ * (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model wrote a second recommendation of the same hotels).
+ */
+const readAsWritten = new WeakMap();
 function waitsForAnswer(message) {
     return CARD_ASK.test(message) || new RegExp(URL_IN_TEXT.source, 'i').test(message);
 }
@@ -767,6 +745,13 @@ export function buyTool(options) {
     if (!client.company && externalUserId !== undefined) {
         throw new TypeError("A shopper's own access token already names the shopper. Leave externalUserId out.");
     }
+    if (o.threadId !== undefined && (typeof o.threadId !== 'string' || o.threadId.trim() === '' || o.threadId.trim().length > 200)) {
+        throw new TypeError('Pass threadId as your own id for the chat or thread, 1 to 200 characters, or leave it out.');
+    }
+    const threadId = o.threadId?.trim();
+    checkStoreWait(o);
+    /** Whether a message is this tool's to read (`messageInChat`): its chat's purchase, or news about the shopper alone. */
+    const inThisThread = (message) => messageInChat(message, threadId);
     if (o.sendLink !== undefined && typeof o.sendLink !== 'function') {
         throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
     }
@@ -838,6 +823,9 @@ export function buyTool(options) {
     const { onWorking, onReaction } = ackRoutes(o.onWorking, o.onReaction);
     /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
+    // When the newest call of this tool started: a late reply on the conversation answers the newest shopper message, so a call
+    // that a newer one followed no longer owns it.
+    let newestCallAt = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
     let lastTemplate = -1;
     /** Counts the model's turns: the calls of one turn share its number. */
@@ -936,6 +924,9 @@ export function buyTool(options) {
     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 = [];
+    /** Every product card this conversation's answers showed, newest first, each once: a tap on an older card reads these. */
+    let shownBefore = [];
+    let shownIn = null;
     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. */
@@ -1272,7 +1263,8 @@ export function buyTool(options) {
      * picks one first. A placement another attempt is still finishing keeps the
      * reading going and ends as `placing`, never as the cart. A minute without
      * any of them returns Agentcard's own answer, or what the last read showed
-     * while the turn still ran.
+     * while the turn still ran. A turn that ended with a reply of its own
+     * (`latest_reply`) answers with that reply and the products it showed.
      */
     const awaitCart = async (base, conversationId, since) => {
         const shown = new Set(base.hashes);
@@ -1307,13 +1299,18 @@ export function buyTool(options) {
                 // conversation and it shows one cart. With carts at two stores `confirm: true` still names the
                 // cart an earlier answer showed, so none is offered: the shopper's pick goes out as an ask.
                 const one = conversation.carts.length === 1 ? newest : null;
+                // The reply the turn wrote after its early answer is what the shopper waited for: it goes out in place of the
+                // tool's own line, with the products it showed (conv_054988b998634b16ab4a91d9, 2026-10-30: a stop message
+                // written while the shopper read "one moment" was never shown, and the model was told to call again).
+                const late = conversation.turn_in_progress || newestCallAt > since ? null : conversation.latest_reply;
                 const answer = {
                     ...base,
-                    reply: one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    reply: late ? late.text : one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    ...(late?.catalog ? { products: productsOfCatalog(late.catalog) } : {}),
                     cart: one,
                     carts: conversation.carts,
                     hashes: conversation.carts.map((c) => c.hash),
-                    error_code: newest ? null : base.error_code,
+                    error_code: newest || late ? null : base.error_code,
                     // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
                     next_action: null,
                     // The early answer judged the pick before the turn finished adding it.
@@ -1750,6 +1747,16 @@ export function buyTool(options) {
             let refusal;
             /** Each message of Agentcard's answer the app showed through onText, in the order the shopper read them: every one means the shopper read the reply. */
             const told = [];
+            /**
+             * Where this call's messages from Agentcard go as they stream: the app's onText, or, for an app that shows the reply as
+             * written, its onMessage once Agentcard says the reply is written (`reply_written`). Until then such an app's
+             * messages are kept in `unsaid`, and a call whose stream never says so shows none of them: the app shows the answer.
+             */
+            let speak = t.onText;
+            // Only where the cards went out as they streamed (earlyCards): a reply shown earlier than its cards would ask the shopper
+            // to choose from hotels they cannot see yet.
+            const writtenText = early ? t.onWrittenText : undefined;
+            const unsaid = [];
             /**
              * The streamed messages that wait for the answer: the first that asks for a card or points at a link (waitsForAnswer),
              * and every message after it, so the shopper reads them in the order Agentcard wrote them.
@@ -1762,7 +1769,7 @@ export function buyTool(options) {
             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 });
+                await speak(messageForShopper(message, leadIn, t.texting), { conversationId });
                 leadIn = leadsIntoList(message);
                 told.push(...texts);
             };
@@ -1802,6 +1809,9 @@ export function buyTool(options) {
             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 = [];
+            /** Whether Agentcard said the reply is written (`reply_written`), and the cards that went out after it: a store that answered late. */
+            let replyWritten = false;
+            const lateCards = [];
             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();
@@ -1863,6 +1873,23 @@ export function buyTool(options) {
                     // The app's display failing never fails the call.
                 }
             };
+            /** One of Agentcard's messages as it streams, to the app through `speak`. */
+            const streamText = async (text, conversationId) => {
+                // A message that lands before the instant reply was due is the reply; one after it follows it.
+                ack?.cancel();
+                await t.ackOut;
+                // A card ask or a link waits for the answer, which may name a step that comes first, and every message after it waits behind it.
+                if (waiting.length > 0 || waitsForAnswer(text)) {
+                    waiting.push({ text, conversationId });
+                    return;
+                }
+                try {
+                    await showText(text, conversationId);
+                }
+                catch {
+                    // A message the app failed to show was never read, so the model words the answer.
+                }
+            };
             // Streamed: the stages go to onProgress, a search's products to onProducts and its store pages out the moment it
             // answers, and each message and cart to the app as Agentcard writes it.
             const handlers = streams
@@ -1901,13 +1928,19 @@ export function buyTool(options) {
                                 // The products past the cards are read after the cards went out, so the first card never waits for them.
                                 const keepMore = () => { if (t.onFound && early)
                                     moreFound = { conversationId: update.conversationId, links: productsOfCatalog({ ...update.catalog, items: update.more }).map(productLink) }; };
-                                if (!early)
+                                if (!early) {
+                                    // Without early cards nothing goes out here, but a store that answered after the reply still joins the result.
+                                    if (replyWritten)
+                                        lateCards.push(...productsOfCatalog(update.catalog));
                                     return;
+                                }
                                 // Products arrived before the instant reply was due: they are the reply.
                                 ack?.cancel();
                                 await t.ackOut;
                                 // The turn's own search presents its products, as a reply that lists them does.
-                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                const out = await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                if (replyWritten)
+                                    lateCards.push(...out.products);
                                 // 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));
@@ -1928,23 +1961,26 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
-                    ...(t.onText
+                    ...(t.onText || writtenText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
-                                // A message that lands before the instant reply was due is the reply; one after it follows it.
-                                ack?.cancel();
-                                await t.ackOut;
-                                // A card ask or a link waits for the answer, which may name a step that comes first, and every message after it waits behind it.
-                                if (waiting.length > 0 || waitsForAnswer(text)) {
-                                    waiting.push({ text, conversationId });
+                                if (!speak) {
+                                    unsaid.push({ text, conversationId });
                                     return;
                                 }
-                                try {
-                                    await showText(text, conversationId);
-                                }
-                                catch {
-                                    // A message the app failed to show was never read, so the model words the answer.
-                                }
+                                await streamText(text, conversationId);
+                            },
+                        }
+                        : {}),
+                    ...(early || t.onProducts
+                        ? {
+                            onReplyWritten: async () => {
+                                replyWritten = true;
+                                if (speak || !writtenText)
+                                    return;
+                                speak = writtenText;
+                                for (const message of unsaid.splice(0))
+                                    await streamText(message.text, message.conversationId);
                             },
                         }
                         : {}),
@@ -1983,10 +2019,18 @@ export function buyTool(options) {
             // 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;
+            // Every request names the tool's thread, so Agentcard continues this chat's purchase and no other.
+            if (threadId)
+                sent = { ...sent, thread_id: threadId };
+            // Every request names how long the reply waits for stores, and what happens to a store that answers after it.
+            sent = { ...sent, ...storeWaitFields(t.storeWait ?? {}, o) };
             if (plan && 'local' in plan) {
                 // Nothing went to Agentcard: the answer is where the purchase stands.
             }
             else {
+                // This call now owns the conversation's newest reply: an earlier call still waiting for its late reply gives it up.
+                // A call that threw on its input, or answered from where the purchase stands, sent nothing and takes none.
+                newestCallAt = Math.max(newestCallAt, startedAt);
                 try {
                     turn = await client.buy(sent, handlers);
                 }
@@ -2003,6 +2047,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;
+                unsaid.length = 0;
+                speak = t.onText;
                 leads = leadInJoiner();
                 heldTexts = [];
                 try {
@@ -2029,7 +2075,7 @@ export function buyTool(options) {
             // a link the answer replaced gives way to its ask for the step Agentcard named, once, after them. All of them go out
             // before any link of the answer.
             let replaced = false;
-            if (waiting.length > 0 && t.onText) {
+            if (waiting.length > 0 && speak) {
                 const rewritten = !!turn && settled.reply !== turn.reply;
                 // 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()));
@@ -2055,7 +2101,7 @@ export function buyTool(options) {
                     }
                 }
             }
-            if (t.onText) {
+            if (speak) {
                 try {
                     await showLeftLead();
                 }
@@ -2068,10 +2114,10 @@ export function buyTool(options) {
             // A reply the shopper read that asks them to choose, with the values named inside a sentence or not at all, is followed
             // by one more message that lists every value on its own line (choiceLines), so no choice is read buried in prose.
             let choiceShown = true;
-            if (t.onText && turn?.choice && told.length > 0 && !messagesListChoice(told, turn.choice)) {
+            if (speak && turn?.choice && told.length > 0 && !messagesListChoice(told, turn.choice)) {
                 const lines = choiceLines(turn.choice);
                 try {
-                    await t.onText(t.texting ? textingStyle(lines) : lines, { conversationId: turn.conversation_id || null });
+                    await speak(t.texting ? textingStyle(lines) : lines, { conversationId: turn.conversation_id || null });
                 }
                 catch {
                     // Not shown, so the shopper has not read the whole answer: the model words it, with the choice it reads.
@@ -2079,8 +2125,14 @@ export function buyTool(options) {
                 }
             }
             const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, paragraphsOf(settled.reply)));
+            // The shopper read the whole answer before the call ended, the late source's message included: the turn's reply is what
+            // they read, and nothing is worded again (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model
+            // wrote a second recommendation of the same hotels).
             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 late reply read from the conversation presents the products of its own catalog, which the early answer never held.
+            const late = settled.envelope?.latest_reply;
+            const presented = turn?.catalog?.presented === true || (late?.text === settled.reply && late?.catalog?.presented === true);
+            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented, 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.
             if (heldCount && (delivered.products?.length ?? 0) > 0) {
                 const held = heldCount;
@@ -2105,11 +2157,15 @@ export function buyTool(options) {
                 : null;
             const result = {
                 ...delivered,
+                // The cards of a store that answered after the reply join the answer's, when the answer does not list them already.
+                ...(lateCards.length > 0 ? { products: withLateCards(delivered.products, lateCards) } : {}),
                 ...(t.ackDelivered ? { shopper_already_told_looking: true } : {}),
                 ...(read ? { shopper_already_read_reply: true } : {}),
                 ...(confirmSent ? { confirm_sent: true } : {}),
                 ...(yesCarried ? { yes_carried: yesCarried } : {}),
             };
+            if (read && speak && speak === writtenText)
+                readAsWritten.set(result, told.join('\n\n'));
             lastNextAction = result.next_action;
             lastReply = result.reply;
             // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
@@ -2159,6 +2215,13 @@ export function buyTool(options) {
             }
             lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
             lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
+            // A new conversation starts the cards shown before afresh; each card keeps its newest showing, up to SHOWN_BEFORE_MAX.
+            if (result.conversation_id && result.conversation_id !== shownIn)
+                shownBefore = [];
+            if (result.conversation_id)
+                shownIn = result.conversation_id;
+            const fresh = new Set(lastTappable.map((product) => product.productId ?? `name:${product.name}`));
+            shownBefore = [...lastTappable, ...shownBefore.filter((product) => !fresh.has(product.productId ?? `name:${product.name}`))].slice(0, SHOWN_BEFORE_MAX);
             lastAnswerStores = storesShown.map((store) => ({ storeId: store.id, name: store.name }));
             t.results?.push(result);
             if (t.onResult) {
@@ -2235,6 +2298,8 @@ export function buyTool(options) {
             return null;
         if (client.company && message.externalUserId !== externalUserId)
             return null;
+        if (!inThisThread(message))
+            return null;
         if (message.eventId && stepped.has(message.eventId))
             return null;
         // A call for the shopper's own message is still running: its answer tells the model where the purchase stands.
@@ -2243,7 +2308,7 @@ export function buyTool(options) {
         if (message.eventId)
             stepped.add(message.eventId);
         if (client.company)
-            client.answered(externalUserId, message);
+            client.answered(externalUserId, message, threadId);
         return openTurn(nextStepPrompt(message), options, message);
     };
     const openTurn = (shopperText, options, event) => {
@@ -2268,6 +2333,7 @@ export function buyTool(options) {
         if (own.textingStyle !== undefined && typeof own.textingStyle !== 'boolean')
             throw new TypeError('Pass textingStyle to the turn as true or false, or leave it out.');
         const texting = own.textingStyle ?? textingByDefault;
+        checkStoreWait(own, ' to the turn');
         const hearText = own.onText ?? o.onText;
         // Messages are spaced only for an app that hears each one as it goes out.
         const pauseOf = paceOf(own.pace);
@@ -2337,7 +2403,14 @@ export function buyTool(options) {
             // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
             // an app that passes onItem too hears it once.
             onText: hearText ? (text, info) => feed.push({ kind: 'text', text }, () => hearText(text, info)) : undefined,
+            // An app that shows the reply as written hears it the moment Agentcard says it is written, when the turn then waits for
+            // a slower source's cards: the reply no longer waits for them (chat.opencommerce.sh, 2026-10-29, a hotel reply written
+            // at about 21 s reached the shopper at 36.5 s, with the second supplier's hotels).
+            onWrittenText: !hearText && written && (onItem || onMessage)
+                ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : onMessage?.(text)))
+                : undefined,
             texting,
+            storeWait: { storeWaitMs: own.storeWaitMs, lateResults: own.lateResults },
             onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
@@ -2430,13 +2503,17 @@ export function buyTool(options) {
         const results = state.results;
         // A pick or an answer goes straight only after a turn that ended on Agentcard's answer, and never while a call still runs.
         const answered = previousTurn !== null && (previousTurn.results?.length ?? 0) > 0;
+        // A tap names its card by the id its link carried, whatever answer showed it: the pick goes straight with that id.
+        const tappedId = typeof options?.tapped?.productId === 'string' && options.tapped.productId.trim() ? options.tapped.productId.trim() : null;
         // A `nextStep` turn's call is the same whatever the model writes (`stepPlan` reads where the purchase stands), so it goes
         // straight too: with `replyAsWritten`, a step whose answer is a link, such as the approval after a saved card, needs no model.
         const direct = !directOn || running > 0
             ? 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, tappable: lastTappable, stores: lastAnswerStores });
+                : tappedId && String(shopperText ?? '').trim()
+                    ? { input: { ask: String(shopperText).trim(), confirm: false, new_order: false, product_id: tappedId, store_id: null }, reason: 'pick' }
+                    : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, shownBefore, 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();
@@ -2504,7 +2581,7 @@ export function buyTool(options) {
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
-        const kept = client.company ? client.keptMessages(externalUserId) : [];
+        const kept = client.company ? client.keptMessages(externalUserId, threadId).filter(inThisThread) : [];
         let handed = null;
         const shopperWords = String(shopperText ?? '');
         /**
@@ -2526,18 +2603,20 @@ export function buyTool(options) {
                 // Another order's update can read the same, so only a history holding the text more often than
                 // when this message first went in holds this message.
                 const count = occurrences(held, JSON.stringify(text).slice(1, -1));
-                const before = offeredAt.get(message);
+                // Each chat counts its own history: a message about the shopper alone goes in to every chat's model.
+                const counts = offeredAt.get(message) ?? new Map();
+                const before = counts.get(threadId ?? '');
                 if (before !== undefined && count > before) {
                     saved.push(message);
                 }
                 else {
                     if (before === undefined)
-                        offeredAt.set(message, count);
+                        offeredAt.set(message, counts.set(threadId ?? '', count));
                     fresh.push(message);
                 }
             }
             if (saved.length > 0)
-                client.forgetMessages(externalUserId, saved);
+                client.forgetMessages(externalUserId, saved, threadId);
             handed = fresh;
             // 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)}`);
@@ -2545,6 +2624,10 @@ export function buyTool(options) {
         /** Says a whole text as the turn's messages, after every item before it (`say()`). */
         const sayWhole = (whole) => {
             writesThroughTurn = true;
+            // The reply the shopper already read as Agentcard wrote it (`readAsWritten`), of the turn's last answer: saying it again sends nothing.
+            const read = results.length > 0 ? readAsWritten.get(results[results.length - 1]) : undefined;
+            if (read && whole === read)
+                return releaseForReply();
             firstWords(whole);
             if (state.modelTurn && /\S/.test(String(whole ?? '')))
                 state.modelTurn.spoke = true;
@@ -2613,7 +2696,7 @@ export function buyTool(options) {
                     if (event.eventId)
                         stepped.delete(event.eventId);
                     if (client.company)
-                        client.unanswered(externalUserId, event);
+                        client.unanswered(externalUserId, event, threadId);
                 },
                 enumerable: false,
             },
@@ -2628,7 +2711,7 @@ export function buyTool(options) {
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
             stopped: { get: () => state.stopped === true, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? readAsWritten.get(results[results.length - 1]) ?? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
             // Each message joins the feed the moment it is cut, so a link the tool hands over during a pause never overtakes text already written.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.